API Reference

Everything is imported from "bosia":

import { cn, sequence, error, redirect, fail } from "bosia";
import type { RequestEvent, LoadEvent, Handle, Cookies } from "bosia";

Functions

cn(...inputs)

Merge Tailwind CSS classes safely. Uses built-in class merging and tailwind-merge.

cn("px-4 py-2", "px-6"); // → "py-2 px-6"
cn("text-red-500", isActive && "text-blue-500");

sequence(...handlers)

Compose multiple Handle middleware into a single handler:

export const handle = sequence(auth, logging, rateLimit);

Handlers execute left-to-right. Each handler's resolve calls the next.

error(status, message)

Throw an HTTP error from a load() function. Renders the nearest +error.svelte.

error(404, "Post not found"); // never returns

redirect(status, location, options?)

Redirect from a load() function or form action.

redirect(303, "/login"); // never returns

Open redirect protection: By default, redirect() only allows relative paths and same-origin URLs. External URLs, protocol-relative URLs (//evil.com), and dangerous schemes (javascript:, data:) are rejected with a descriptive error.

To redirect to an external URL (e.g., an OAuth provider), pass { allowExternal: true }:

redirect(303, "https://oauth.provider.com/authorize?...", {
	allowExternal: true,
});

fail(status, data)

Return a validation failure from a form action. Returned, not thrown.

return fail(400, { email, errors: { email: "Required" } });

Types

RequestEvent

Available in API routes (+server.ts) and form actions.

type RequestEvent = {
	request: Request;
	url: URL;
	locals: Record<string, any>;
	params: Record<string, string>;
	cookies: Cookies;
};

LoadEvent

Available in load() functions in +page.server.ts and +layout.server.ts.

type LoadEvent = {
	url: URL;
	params: Record<string, string>;
	locals: Record<string, any>;
	cookies: Cookies;
	fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
	parent: () => Promise<Record<string, any>>;
	metadata: Record<string, any> | null;
};

MetadataEvent

Available in metadata() functions in +page.server.ts.

type MetadataEvent = {
	params: Record<string, string>;
	url: URL;
	locals: Record<string, any>;
	cookies: Cookies;
	fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
};

Metadata

Return type for metadata() functions.

type Metadata = {
	title?: string;
	description?: string;
	meta?: Array<{ name?: string; property?: string; content: string }>;
	data?: Record<string, any>;
};

Handle

Middleware function type for hooks.server.ts.

type Handle = (input: { event: RequestEvent; resolve: ResolveFunction }) => MaybePromise<Response>;

Cookies

Cookie read/write interface available on event.cookies.

interface Cookies {
	get(name: string): string | undefined;
	getAll(): Record<string, string>;
	set(name: string, value: string, options?: CookieOptions): void;
	delete(name: string, options?: Pick<CookieOptions, "path" | "domain">): void;
}

CookieOptions

interface CookieOptions {
	path?: string;
	domain?: string;
	maxAge?: number; // seconds
	expires?: Date;
	httpOnly?: boolean;
	secure?: boolean;
	sameSite?: "Strict" | "Lax" | "None";
}

HttpError

Error class thrown by error().

class HttpError extends Error {
	status: number;
}

Redirect

Redirect class thrown by redirect(). Validates the location at construction time to prevent open redirects.

class Redirect {
	status: number;
	location: string;
}

RedirectOptions

interface RedirectOptions {
	/** Allow redirects to external origins. */
	allowExternal?: boolean;
}

ActionFailure\

Returned by fail() in form actions.

class ActionFailure<T extends Record<string, any>> {
	status: number;
	data: T;
}

CsrfConfig

interface CsrfConfig {
	checkOrigin: boolean;
	allowedOrigins?: string[];
}

CorsConfig

interface CorsConfig {
	allowedOrigins: string[];
	allowedMethods?: string[];
	allowedHeaders?: string[];
	exposedHeaders?: string[];
	credentials?: boolean;
	maxAge?: number;
}

Import Patterns

Import	Source
import { cn, sequence } from "bosia"	Framework package
import { cn } from "$lib/utils"	Project utility
import { VAR } from "$env"	Environment vars
import type { PageData } from "./$types"	Generated types