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. Combines clsx 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)

Redirect from a load() function or form action.

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

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().

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

ActionFailure<T>

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