ajo-kit 0.1.0

package/src/cache.ts

@@ -0,0 +1,85 @@
+import type { State } from './constants'
+
+export const max = 50
+export const ttl = 5 * 60 * 1000
+
+type Meta = {
+	cached: number
+	used: number
+}
+
+const cache = new Map<string, State>()
+
+const meta = new Map<string, Meta>()
+
+const now = () => Date.now()
+
+const remove = (url: string) => {
+	cache.delete(url)
+	meta.delete(url)
+}
+
+export const clear = () => {
+	cache.clear()
+	meta.clear()
+}
+
+export const get = (url: string, time = now()) => {
+	const state = cache.get(url)
+	const info = meta.get(url)
+
+	if (!state || !info) return
+
+	if (time - info.cached > ttl) {
+		remove(url)
+		return
+	}
+
+	info.used = time
+
+	return state
+}
+
+const prune = (active?: string, time = now()) => {
+	for (const [url, info] of meta) {
+		if (url !== active && time - info.cached > ttl) remove(url)
+	}
+
+	while (cache.size > max) {
+		let candidate: string | undefined
+		let oldest = Infinity
+
+		for (const [url, info] of meta) {
+			if (url === active) continue
+			if (info.used < oldest) {
+				oldest = info.used
+				candidate = url
+			}
+		}
+
+		if (!candidate) break
+
+		remove(candidate)
+	}
+}
+
+export const set = (url: string, state: State, options?: { active?: string; now?: number }) => {
+	const time = options?.now ?? now()
+
+	cache.set(url, state)
+	meta.set(url, { cached: time, used: time })
+	prune(options?.active ?? url, time)
+}
+
+export const invalidate = (topics?: string[]) => {
+	if (!topics?.length) {
+		clear()
+		return
+	}
+
+	const changed = new Set(topics)
+
+	for (const [url, state] of cache) {
+		if (!state.topics?.length || state.topics.some(topic => changed.has(topic))) remove(url)
+	}
+}

package/src/client.tsx

@@ -0,0 +1,167 @@
+import { render } from 'ajo'
+import { current } from 'ajo/context'
+import App, { init } from './app'
+import type { State, Action } from './constants'
+import { navigate } from './constants'
+import { fields, body as make } from './form'
+import { parse } from './ssr'
+import { invalidate } from './cache'
+
+// Action helper for stateful generator components
+
+/** Creates state and submit/invoke helpers for a route action. */
+export function action<T = unknown>(name?: string, init?: RequestInit): Action<T> {
+
+	const component = current()
+
+	if (!component) throw new Error('action() must be called inside a stateful component.')
+
+	let controller: AbortController | undefined
+
+	const state: Action<T> = {
+		loading: false,
+		data: undefined,
+		error: undefined,
+		submit: () => { },
+		invoke: (value?) => run(value),
+		reset: () => {
+			const current = controller
+
+			controller = undefined
+			current?.abort()
+			state.loading = false
+			state.data = undefined
+			state.error = undefined
+			component.next()
+		}
+	}
+
+	const run = async (value: unknown): Promise<T | undefined> => {
+
+		controller?.abort()
+		const current = controller = new AbortController()
+
+		const forwardAbort = (signal?: AbortSignal | null) => {
+			if (!signal) return
+			if (signal.aborted) current.abort(signal.reason)
+			else signal.addEventListener('abort', () => current.abort(signal.reason), { once: true, signal: current.signal })
+		}
+
+		forwardAbort(component.signal)
+		forwardAbort(init?.signal)
+
+		state.loading = true
+		state.error = undefined
+		component.next()
+
+		try {
+
+			const response = await fetch(name ? `?/${name}` : '', {
+				method: 'POST',
+				credentials: 'include',
+				headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
+				body: JSON.stringify(value),
+				...init,
+				signal: current.signal,
+			})
+
+			const json = await response.json().catch(() => null) as
+				| { redirect?: string; topics?: string[]; versions?: Record<string, number>; error?: { status?: number; message?: string; fields?: Record<string, string[] | undefined> }; message?: string; fields?: Record<string, string[] | undefined> }
+				| null
+
+			if (controller !== current || current.signal.aborted) return
+
+			if (!response.ok) {
+
+				state.error = {
+					status: json?.error?.status ?? response.status,
+					message: json?.error?.message ?? json?.message ?? 'Action failed',
+					fields: json?.error?.fields ?? json?.fields
+				}
+
+				return
+			}
+
+			invalidate(json?.topics)
+
+			if (json?.redirect) {
+				navigate(json.redirect)
+				return
+			}
+
+			state.data = (json ?? {}) as T
+			globalThis.dispatchEvent?.(new CustomEvent('ajo:action', { detail: json ?? {} }))
+
+			return state.data
+
+		} catch (error) {
+
+			if (current.signal.aborted || error instanceof Error && error.name === 'AbortError') return
+
+			if (controller !== current) return
+
+			state.error = {
+				status: 500,
+				message: error instanceof Error ? error.message : 'Action failed'
+			}
+
+			return
+
+		} finally {
+			if (controller === current) {
+				controller = undefined
+				state.loading = false
+				component.next()
+			}
+		}
+	}
+
+	state.submit = (event: SubmitEvent) => {
+		event.preventDefault()
+		const form = event.target as HTMLFormElement
+		const data = make(new FormData(form), fields(form))
+		run(data).then(() => { if (!state.error) form.reset() })
+	}
+
+	return state
+}
+
+if (!import.meta.env.SSR) {
+	const script = globalThis.document?.getElementById('__SSR__')
+	const data = script?.textContent ? parse<State>(script.textContent) : null
+	init(data)
+}
+
+if (import.meta.hot) {
+
+	const HMR = Symbol.for('ajo.hmr')
+	const Generator = Symbol.for('ajo.generator')
+	const Iterator = Symbol.for('ajo.iterator')
+	const Memo = Symbol.for('ajo.memo')
+
+	type HMRElement = Element & {
+		[Generator]?: { [HMR]?: string } | null
+		[Iterator]?: unknown
+		[Memo]?: unknown
+	}
+
+	const walk = (el: HMRElement, path?: string): void => {
+		if (el[Generator]?.[HMR] == path) el[Iterator] = el[Generator] = null
+		el[Memo] = null
+		Array.from(el.children).forEach(child => walk(child, path))
+	}
+
+	const root = document.getElementById('root');
+
+	(globalThis as { __HMR__?: (path?: string) => void }).__HMR__ = path => {
+		if (root) walk(root, path)
+		dispatchEvent(new CustomEvent('hmr'))
+	}
+}
+
+const root = globalThis?.document?.getElementById('root')
+
+if (root) {
+	render(<App />, root)
+	document.documentElement.dataset.ajoReady = 'true'
+}

package/src/constants.ts

@@ -0,0 +1,339 @@
+import type { Children, Component } from 'ajo'
+import type { Params } from 'navaid'
+import type { Request, Response, Middleware } from 'polka'
+/** Polka request, response, and middleware types used by route modules. */
+export type { Request, Response, Middleware }
+/** Document head payload returned by route head loaders. */
+export type { Head } from './head'
+import type { Head } from './head'
+import type { Timing } from './timing'
+
+// Route errors with HTTP status codes
+
+/** HTTP-aware error serialized by loaders, actions, and API handlers. */
+export class Failure extends Error {
+
+	constructor(public status: number, message: string) {
+		super(message)
+	}
+
+	toJSON() {
+		return {
+			message: mask(this.status, this.message),
+			status: this.status,
+			...(!production() && import.meta.env.DEV && { stack: this.stack })
+		}
+	}
+}
+
+/** 404 error for missing routes or resources. */
+export class Missing extends Failure {
+	constructor(message = 'Page not found') {
+		super(404, message)
+	}
+}
+
+/** 403 error for authenticated users without enough access. */
+export class Forbidden extends Failure {
+	constructor(message = 'Access denied') {
+		super(403, message)
+	}
+}
+
+/** 401 error for requests that need authentication. */
+export class Denied extends Failure {
+	constructor(message = 'Authentication required') {
+		super(401, message)
+	}
+}
+
+/** Field-level validation errors keyed by form field name. */
+export type Fields = Record<string, string[] | undefined>
+
+/** Client action error shape exposed by action() state. */
+export type Issue = {
+	status: number
+	message: string
+	fields?: Fields
+}
+
+/** 400 validation error carrying field-level messages. */
+export class Invalid extends Failure {
+	constructor(public fields: Fields, message = 'Validation failed') {
+		super(400, message)
+	}
+	toJSON() {
+		return {
+			message: mask(this.status, this.message),
+			status: this.status,
+			fields: this.fields,
+			...(!production() && import.meta.env.DEV && { stack: this.stack })
+		}
+	}
+}
+
+const production = () => process.env.NODE_ENV === 'production'
+const mask = (status: number, message: string) =>
+	production() && status >= 500 ? 'Internal Server Error' : message
+const config = (message: string) => {
+	if (production()) console.error(`[security] ${message}`)
+	return new Failure(500, message)
+}
+const code = (error: unknown) => {
+	if (!error || typeof error !== 'object') return 500
+
+	const value = (error as { status?: unknown }).status ?? (error as { statusCode?: unknown }).statusCode
+
+	return Number.isInteger(value) && (value as number) >= 400 && (value as number) <= 599
+		? value as number
+		: 500
+}
+const message = (error: unknown, status: number) => {
+	if (status === 413) return 'Content Too Large'
+	if (error instanceof Error && error.message) return error.message
+	return status < 500 ? 'Request failed' : 'Unknown error'
+}
+
+/** Converts any thrown value into a framework Failure. */
+export function normalize(error: unknown): Failure {
+	if (error instanceof Failure) return error
+	const status = code(error)
+	return new Failure(status, message(error, status))
+}
+
+// Route path utilities
+
+/** Returns route ancestor keys from outermost to innermost. */
+export const ancestors = (segments: string[]) => segments.map((_, i) => segments.slice(0, i + 1).join('/'))
+
+// Loader data types
+
+/** Data object returned by one loader. */
+export type Entry = Record<string, unknown>
+
+/** Ordered loader data for layouts followed by the page. */
+export type Data = Entry[]
+
+/** Server payload containing head data followed by loader entries. */
+export type Payload = [Head, ...Data]
+
+/** Reads merged data from ancestor loaders. */
+export type Parent = () => Promise<Entry>
+
+// Route module types
+
+/** Runtime shape of a route page or layout module. */
+export type Module = {
+	default: Component
+	/** Receives loading=true while client navigation is pending. */
+	pending?: boolean
+}
+
+/** Lazy module loader generated by Vite route globs. */
+export type Loader = () => Promise<Module>
+
+/** Compiled route page metadata used by the client and server routers. */
+export type Page = {
+	loader: Loader
+	segments: string[]
+	pattern?: string
+	params?: Params
+}
+
+/** Client route state produced by SSR, JSON loads, and navigation. */
+export interface State {
+	url: string
+	params: Params
+	data: Data
+	loading: boolean
+	error?: Failure
+	head?: Head
+	hash?: string
+	topics?: string[]
+	versions?: Record<string, number>
+}
+
+/** State and commands returned by the client action() helper. */
+export type Action<T> = {
+	loading: boolean
+	data?: T
+	error?: Issue
+	submit: (event: SubmitEvent) => void
+	invoke: (body?: unknown) => Promise<T | undefined>
+	/** Aborts any in-flight request and clears loading, data, and error state. */
+	reset: () => void
+}
+
+// Page and layout args
+
+/** Route page component args. */
+export type PageArgs<T = Entry> = {
+	params: Params
+	data?: T
+	loading: boolean
+	error?: Failure
+}
+
+/** Route layout component args, including children. */
+export type LayoutArgs<T = Entry> = PageArgs<T> & {
+	children: Children
+}
+
+// Navigation helper
+
+/** Pushes a browser URL and asks the client router to navigate. */
+export const navigate = (to: string) => {
+	globalThis.history?.pushState({}, '', to)
+	globalThis.dispatchEvent?.(new CustomEvent('ajo:navigate'))
+}
+
+// Request helpers
+
+/** Returns true when a request expects JSON route/action data. */
+export const ajax = (req: Request) => !!req.headers.accept?.includes('application/json')
+/** Returns true when a request targets the /api route namespace. */
+export const api = (req: Request) => req.path.startsWith('/api/')
+
+const enabled = (value: string | undefined) => value === '1' || value?.toLowerCase() === 'true'
+const proxy = () => enabled(process.env.TRUST_PROXY)
+
+const first = (value: string | string[] | undefined) =>
+	Array.isArray(value) ? value[0] : value
+
+const address = (value: string) => {
+	const raw = value.trim().replace(/^\[/, '').replace(/\]$/, '').replace(/^::ffff:/, '')
+	return raw === '::1' || raw === '127.0.0.1' ? 'localhost' : raw
+}
+
+const ipv4 = (value: string) => {
+	const parts = value.split('.')
+	return parts.length === 4 && parts.every(part => {
+		if (!/^\d{1,3}$/.test(part)) return false
+		const number = Number(part)
+		return number >= 0 && number <= 255
+	})
+}
+
+const ipv6 = (value: string) =>
+	value.includes(':') && /^[0-9a-f:.]+$/i.test(value)
+
+const local = (host: string) => {
+	try {
+		return address(new URL(`http://${host}`).hostname) === 'localhost'
+	} catch {
+		return false
+	}
+}
+
+const forwarded = (header: string | string[] | undefined) => {
+	const value = first(header)
+	if (!value) return
+
+	const addr = address(value.split(',')[0])
+	if (addr === 'localhost' || ipv4(addr) || ipv6(addr)) return addr
+}
+
+/** Resolves the client IP, honoring TRUST_PROXY for forwarded headers. */
+export const ip = (req: Request) => {
+	const raw = proxy()
+		? forwarded(req.headers['x-forwarded-for']) ?? req.socket?.remoteAddress
+		: req.socket?.remoteAddress
+
+	return raw ? address(raw) : 'unknown'
+}
+
+/** Resolves the trusted app origin from APP_URL or the request host. */
+export const origin = (req: Request) => {
+	const configured = process.env.APP_URL
+
+	if (configured) {
+		try {
+			const url = new URL(configured)
+			if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error()
+			return url.origin
+		} catch {
+			throw config('Invalid APP_URL')
+		}
+	}
+
+	const host = req.headers.host
+	if (!host) throw new Failure(400, 'Missing Host header')
+
+	if (production() && !local(host)) {
+		throw config('APP_URL is required in production')
+	}
+
+	const forwarded = first(req.headers['x-forwarded-proto'])?.split(',')[0]?.trim()
+	const protocol = proxy() && (forwarded === 'http' || forwarded === 'https') ? forwarded : 'http'
+
+	try {
+		return new URL(`${protocol}://${host}`).origin
+	} catch {
+		throw new Failure(400, 'Invalid Host header')
+	}
+}
+
+// Auth types
+
+/** Authenticated user shape attached to requests by auth middleware. */
+export interface User {
+	id: number
+	roles?: string[]
+	abilities?: string[]
+	[key: string]: unknown
+}
+
+// Request extensions for polka
+
+declare module 'polka' {
+	interface Request {
+		user?: User
+		session?: { id: string }
+		token?: { id: string; abilities: string[] }
+		topics?: Set<string>
+		track?: (topic: string | string[]) => void
+		verifyLive?: () => Promise<boolean>
+		timing?: Timing
+		revalidate?: () => Promise<Payload>
+		head?: Head
+		entries?: Data
+	}
+}
+
+// Deferred promises for parallel loader execution
+
+/** Internal parent/deferred link used to run loaders in parallel. */
+export type Link = {
+	parent: Parent
+	deferred: { promise: Promise<Entry>; resolve: (value: Entry) => void; reject: (error: Error) => void }
+}
+
+/** Builds parent/deferred links for a loader chain. */
+export function links(count: number): Link[] {
+
+	const chain: Link[] = []
+
+	for (let depth = 0; depth < count; depth++) {
+
+		let resolve!: (value: Entry) => void
+		let reject!: (error: Error) => void
+
+		const promise = new Promise<Entry>((res, rej) => {
+			resolve = res
+			reject = rej
+		})
+
+		const parent = async () =>
+			Object.assign({}, ...await Promise.all(chain.slice(0, depth).map(link => link.deferred.promise)))
+
+		chain.push({ parent, deferred: { promise, resolve, reject } })
+	}
+
+	return chain
+}
+
+// Formatting
+
+/** Formats an ISO date for the current locale with compact defaults. */
+export const date = (iso: string, options?: Intl.DateTimeFormatOptions) =>
+	new Date(iso).toLocaleDateString(undefined, options ?? { month: 'short', day: 'numeric', year: 'numeric' })

package/src/database.ts

@@ -0,0 +1,55 @@
+import { createRequire } from 'node:module'
+import { Kysely, SqliteDialect } from 'kysely'
+import type * as BetterSqlite3 from 'better-sqlite3'
+
+const require = createRequire(import.meta.resolve('ajo-kit'))
+
+/** Kysely SQL template helper. */
+export { sql } from 'kysely'
+/** Kysely database and row helper types. */
+export type { Kysely, Generated, Selectable, Insertable } from 'kysely'
+/** better-sqlite3 constructor resolved from ajo-kit's own installation. */
+export const Database = require('better-sqlite3') as typeof import('better-sqlite3')
+/** better-sqlite3 database handle type. */
+export type Database = BetterSqlite3.Database
+/** Alias for the active SQLite database handle. */
+export type Sqlite = Database
+
+let sqlite: Sqlite | null = null
+let instance: Kysely<any> | null = null
+
+/** Opens the SQLite database and configures safe defaults. */
+export function connect(path = './database.sqlite'): Sqlite {
+	sqlite = new Database(path)
+	sqlite.pragma('journal_mode = WAL')
+	sqlite.pragma('foreign_keys = ON')
+	sqlite.pragma('busy_timeout = 5000')
+	sqlite.pragma('synchronous = NORMAL')
+	return sqlite
+}
+
+/** Returns the shared Kysely instance, opening SQLite on first use. */
+export function db<T = any>(): Kysely<T> {
+	if (!sqlite) connect()
+	return instance ??= new Kysely<T>({
+		dialect: new SqliteDialect({ database: sqlite! })
+	})
+}
+
+/** Returns the shared raw better-sqlite3 handle. */
+export function raw(): Sqlite {
+	if (!sqlite) connect()
+	return sqlite!
+}
+
+/** Destroys the shared Kysely instance and closes SQLite. */
+export async function close(): Promise<void> {
+	if (instance) {
+		await instance.destroy()
+		instance = null
+	}
+	if (sqlite) {
+		sqlite.close()
+		sqlite = null
+	}
+}

package/src/discover.ts

@@ -0,0 +1,42 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface Plugin {
+	name: string
+	path: string
+	alias?: string
+	serverOnly?: boolean
+	migrations?: string
+	commands?: string
+}
+
+export function discover(root = process.cwd()): Plugin[] {
+
+	const modules = join(root, 'node_modules')
+	const plugins: Plugin[] = []
+
+	let entries: string[]
+	try { entries = readdirSync(modules) } catch { return plugins }
+
+	for (const entry of entries) {
+
+		if (!entry.startsWith('ajo-') || entry === 'ajo-kit') continue
+
+		const dir = join(modules, entry)
+		let pkg: any
+
+		try { pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) } catch { continue }
+
+		if (!pkg.kit) continue
+
+		plugins.push({
+			name: pkg.name,
+			path: dir,
+			...pkg.kit,
+			...(pkg.kit.migrations && { migrations: join(dir, pkg.kit.migrations) }),
+			...(pkg.kit.commands && { commands: join(dir, pkg.kit.commands) }),
+		})
+	}
+
+	return plugins
+}