ajo-kit 0.1.0

package/src/form.ts

@@ -0,0 +1,39 @@
+export function fields(form: HTMLFormElement): Set<string> {
+
+	const seen = new Set<string>()
+	const arrays = new Set<string>()
+
+	for (const element of Array.from(form.elements)) {
+
+		const control = element as HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement
+		const name = control.name
+
+		if (!name) continue
+
+		if (seen.has(name) || control instanceof HTMLSelectElement && control.multiple) arrays.add(name)
+		else seen.add(name)
+	}
+
+	return arrays
+}
+
+export function body(
+	data: FormData,
+	arrays: Set<string> = new Set()
+): Record<string, string | string[]> {
+
+	const body: Record<string, string | string[]> = {}
+
+	for (const [name, value] of data) {
+
+		if (typeof value !== 'string') continue
+
+		const current = body[name]
+
+		if (current === undefined) body[name] = arrays.has(name) ? [value] : value
+		else if (Array.isArray(current)) current.push(value)
+		else body[name] = [current, value]
+	}
+
+	return body
+}

package/src/freshness.ts

@@ -0,0 +1,63 @@
+export type Versions = Record<string, number>
+
+const versions = new Map<string, number>()
+
+export function hash(value: string) {
+	let h = 2166136261
+
+	for (let i = 0; i < value.length; i++) {
+		h ^= value.charCodeAt(i)
+		h = Math.imul(h, 16777619)
+	}
+
+	return (h >>> 0).toString(36)
+}
+
+export function topics(topic: string | string[]) {
+	return [...new Set(Array.isArray(topic) ? topic : [topic])].filter(Boolean).sort()
+}
+
+export function bump(topic: string | string[]) {
+	const list = topics(topic)
+
+	for (const t of list) versions.set(t, (versions.get(t) ?? 0) + 1)
+
+	return list
+}
+
+export function snapshot(keys: Iterable<string>): Versions {
+	const result: Versions = {}
+
+	for (const topic of [...keys].sort()) result[topic] = versions.get(topic) ?? 0
+
+	return result
+}
+
+export function parse(raw: string | string[] | undefined): Versions | null {
+	if (!raw || Array.isArray(raw)) return null
+
+	try {
+		const parsed = JSON.parse(raw) as unknown
+		if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+
+		const result: Versions = {}
+
+		for (const [topic, version] of Object.entries(parsed)) {
+			if (typeof version !== 'number' || !Number.isFinite(version)) return null
+			result[topic] = version
+		}
+
+		return result
+	} catch {
+		return null
+	}
+}
+
+export function fresh(client: Versions | null) {
+	const entries = Object.entries(client ?? {})
+	return entries.length > 0 && entries.every(([topic, version]) => (versions.get(topic) ?? 0) === version)
+}
+
+export function reset() {
+	versions.clear()
+}

package/src/head.tsx

@@ -0,0 +1,125 @@
+// Types
+
+type Meta =
+	| { name: string; content: string }
+	| { property: string; content: string }
+	| { httpEquiv: string; content: string }
+
+type Link = { rel: string; href: string; [key: string]: string | undefined }
+
+/** Document head fields route modules can return from head(). */
+export type Head = {
+	title?: string
+	meta?: Meta[]
+	link?: Link[]
+}
+
+// Key extractor for deduplication
+
+const key = {
+	meta: (entry: Meta) => 'name' in entry ? entry.name : 'property' in entry ? entry.property : entry.httpEquiv,
+	link: (entry: Link) => entry.rel,
+}
+
+const append = <T,>(items: T[], index: Map<string, number>, entry: T, id: string) => {
+	const position = index.get(id)
+
+	if (position === undefined) {
+		index.set(id, items.length)
+		items.push(entry)
+		return
+	}
+
+	items[position] = entry
+}
+
+// Merge: dedupe by key, last wins
+
+/** Merges route heads, letting later meta/link entries win by key. */
+export function merge(...heads: (Head | undefined)[]): Head {
+
+	const result: Head = {}
+	const meta: Meta[] = []
+	const link: Link[] = []
+	const index = { meta: new Map<string, number>(), link: new Map<string, number>() }
+
+	for (const head of heads) {
+
+		if (!head) continue
+
+		if (head.title) result.title = head.title
+
+		for (const entry of head.meta ?? []) append(meta, index.meta, entry, key.meta(entry))
+		for (const entry of head.link ?? []) append(link, index.link, entry, key.link(entry))
+	}
+
+	if (meta.length) result.meta = meta
+	if (link.length) result.link = link
+
+	return result
+}
+
+// SSR: render to HTML string
+
+const text = (value: string) => value
+	.replace(/&/g, '&amp;')
+	.replace(/</g, '&lt;')
+	.replace(/>/g, '&gt;')
+
+const attribute = (value: string) => text(value).replace(/"/g, '&quot;')
+
+const attrs = (entries: Record<string, string | undefined>) =>
+	Object.entries(entries)
+		.filter((entry): entry is [string, string] => entry[1] !== undefined)
+		.map(([name, value]) => `${name}="${attribute(value)}"`)
+		.join(' ')
+
+const tag = (name: 'meta' | 'link', entries: Record<string, string | undefined>) =>
+	`<${name} ${attrs(entries)}>`
+
+/** Renders a Head object into SSR-safe HTML tags. */
+export function render(head: Head = {}): string {
+
+	const tags: string[] = []
+
+	if (head.title) tags.push(`<title>${text(head.title)}</title>`)
+
+	for (const entry of head.meta ?? []) tags.push(tag('meta', entry))
+	for (const entry of head.link ?? []) tags.push(tag('link', entry))
+
+	return tags.join('\n  ')
+}
+
+// CSR: update document.head (diff before mutate)
+
+/** Applies a Head object to document.head during client navigation. */
+export function apply(head: Head = {}): void {
+
+	if (head.title && document.title !== head.title) document.title = head.title
+
+	const upsert = (selector: string, attrs: Record<string, string>) => {
+
+		let node = document.head.querySelector(selector)
+
+		if (!node) {
+			node = document.createElement(selector.startsWith('link') ? 'link' : 'meta')
+			for (const [attr, value] of Object.entries(attrs)) node.setAttribute(attr, value)
+			document.head.appendChild(node)
+			return
+		}
+
+		for (const [attr, value] of Object.entries(attrs)) {
+			if (node.getAttribute(attr) !== value) node.setAttribute(attr, value)
+		}
+	}
+
+	for (const entry of head.meta ?? []) {
+		const id = key.meta(entry)
+		const selector = 'name' in entry ? `meta[name="${id}"]` : 'property' in entry ? `meta[property="${id}"]` : `meta[http-equiv="${id}"]`
+		upsert(selector, entry as Record<string, string>)
+	}
+
+	for (const entry of head.link ?? []) {
+		upsert(`link[rel="${entry.rel}"]`, entry as Record<string, string>)
+	}
+}

package/src/headers.ts

@@ -0,0 +1,32 @@
+type Value = string | number | readonly string[]
+
+type Target = {
+	setHeader(key: string, value: Value): unknown
+	hasHeader(key: string): boolean
+}
+
+const https = () => {
+	if (process.env.NODE_ENV !== 'production' || !process.env.APP_URL) return false
+
+	try {
+		return new URL(process.env.APP_URL).protocol === 'https:'
+	} catch {
+		return false
+	}
+}
+
+/** Security headers shared by dynamic SSR responses and static assets. */
+export const security = () => ({
+	'X-Content-Type-Options': 'nosniff',
+	'Referrer-Policy': 'strict-origin-when-cross-origin',
+	'Permissions-Policy': 'camera=(), microphone=(), geolocation=(), payment=(), usb=()',
+	'Content-Security-Policy': "frame-ancestors 'none'",
+	...(https() && { 'Strict-Transport-Security': 'max-age=31536000; includeSubDomains' }),
+})
+
+/** Writes headers, optionally preserving values already set downstream. */
+export const set = (res: Target, values: Record<string, Value>, missing = false) => {
+	for (const [key, value] of Object.entries(values)) {
+		if (!missing || !res.hasHeader(key)) res.setHeader(key, value)
+	}
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/// <reference path="./virtual.d.ts" />
+
+export {
+	Failure,
+	Missing,
+	Forbidden,
+	Denied,
+	Invalid,
+	normalize,
+	navigate,
+	ajax,
+	api,
+	ip,
+	origin,
+	date,
+} from './constants'
+
+export type {
+	Request,
+	Response,
+	Middleware,
+	Head,
+	Fields,
+	Issue,
+	Entry,
+	Parent,
+	Action,
+	PageArgs,
+	LayoutArgs,
+	User,
+} from './constants'

package/src/mail/index.ts

@@ -0,0 +1,25 @@
+/** Email payload passed to the configured transport. */
+export interface Mail {
+	to: string
+	subject: string
+	text: string
+	html?: string
+}
+
+/** Async mail transport used by send(). */
+export type Transport = (mail: Mail) => Promise<void>
+
+let transport: Transport = async (mail) => {
+	console.log('📧 Email:', mail.to, '-', mail.subject)
+	console.log(mail.text)
+}
+
+/** Sets the process-wide mail transport. */
+export function configure(handler: Transport): void {
+	transport = handler
+}
+
+/** Sends one email through the configured transport. */
+export async function send(mail: Mail): Promise<void> {
+	await transport(mail)
+}

package/src/migrate.ts

@@ -0,0 +1,132 @@
+import type { Kysely } from 'kysely'
+import { FileMigrationProvider, Migrator, type Migration } from 'kysely/migration'
+import { existsSync, promises as fs } from 'node:fs'
+import * as path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { discover } from './discover'
+
+type Migrations = Record<string, Migration>
+type Source = { folder: string; id: string }
+
+const extensions = ['.js', '.ts', '.mjs', '.mts', '.cjs', '.cts']
+const pattern = /^(\d{4})_[a-z0-9]+(?:_[a-z0-9]+)*$/
+
+const file = (name: string) =>
+	!name.includes('.d.') && extensions.some(extension => name.endsWith(extension))
+
+function validate(id: string, names: string[]) {
+	for (const [index, name] of names.entries()) {
+		const sequence = pattern.exec(name)?.[1]
+		const expected = String(index + 1).padStart(4, '0')
+
+		if (sequence !== expected) {
+			throw new Error(
+				`${id} migrations must be a contiguous sequence starting at 0001; ` +
+					`expected ${expected}_*, found ${name}`
+			)
+		}
+	}
+}
+
+function local(id: string, files: string[]) {
+	const names = files
+		.filter(file)
+		.map(name => name.slice(0, name.lastIndexOf('.')))
+		.sort()
+
+	if (new Set(names).size !== names.length) {
+		throw new Error(`${id} has duplicate migration filenames`)
+	}
+
+	validate(id, names)
+	return names
+}
+
+export function migrationFile(files: string[], name: string) {
+	const safe = name.trim().toLowerCase()
+		.replace(/[^a-z0-9]+/g, '_')
+		.replace(/^_+|_+$/g, '')
+	if (!safe) throw new Error('Migration name must contain a letter or number')
+
+	const number = local('project', files).length + 1
+	if (number > 9_999) throw new Error('Migration sequence exhausted')
+
+	return `${String(number).padStart(4, '0')}_${safe}.ts`
+}
+
+async function load(source: Source): Promise<Migrations> {
+	const names = local(source.id, await fs.readdir(source.folder))
+
+	const migrations = await new FileMigrationProvider({
+		fs,
+		path,
+		migrationFolder: source.folder,
+		import: file => import(pathToFileURL(file).href),
+	}).getMigrations()
+	const incomplete = names.filter(name =>
+		typeof migrations[name]?.up !== 'function' || typeof migrations[name]?.down !== 'function'
+	)
+	if (incomplete.length) {
+		throw new Error(`${source.id} migrations must export up() and down(): ${incomplete.join(', ')}`)
+	}
+
+	return migrations
+}
+
+async function merge(sources: Source[]): Promise<Migrations> {
+	const merged: Migrations = {}
+	const ids = new Set<string>()
+
+	for (const source of sources) {
+		if (ids.has(source.id)) throw new Error(`Duplicate migration source "${source.id}"`)
+		ids.add(source.id)
+
+		for (const [name, migration] of Object.entries(await load(source))) {
+			const qualified = `${source.id}/${name}`
+			merged[qualified] = migration
+		}
+	}
+
+	return merged
+}
+
+export function migrator(instance: Kysely<any>, root = process.cwd()): Migrator {
+	const sources: Source[] = discover(root)
+		.filter(plugin => plugin.migrations)
+		.sort((left, right) => left.name.localeCompare(right.name))
+		.map(plugin => ({ folder: plugin.migrations!, id: `plugin/${plugin.name}` }))
+	const project = path.join(root, 'db/migrations')
+	if (existsSync(project)) sources.push({ folder: project, id: 'project' })
+
+	return new Migrator({
+		db: instance,
+		// Plugins can gain migrations after a project migration has run. Folder-level
+		// validation keeps each source strict while Kysely ignores only global interleaving.
+		allowUnorderedMigrations: true,
+		provider: {
+			async getMigrations() {
+				return merge(sources)
+			}
+		}
+	})
+}
+
+export async function migrationStatus(instance: Kysely<any>, root = process.cwd()) {
+	const migrations = await migrator(instance, root).getMigrations()
+	const history = await instance
+		.selectFrom('sqlite_master')
+		.select('name')
+		.where('type', '=', 'table')
+		.where('name', '=', 'kysely_migration')
+		.executeTakeFirst()
+	if (!history) return migrations
+
+	const available = new Set(migrations.map(migration => migration.name))
+	const executed = await instance.selectFrom('kysely_migration').select('name').execute()
+	const missing = executed.map(migration => migration.name).filter(name => !available.has(name)).sort()
+	if (missing.length) {
+		throw new Error(`Migration history references missing migrations: ${missing.join(', ')}`)
+	}
+
+	return migrations
+}

package/src/node.ts

@@ -0,0 +1,134 @@
+import fs from 'node:fs/promises'
+import * as url from 'node:url'
+import { join } from 'node:path'
+import * as http from 'node:http'
+import * as vite from 'vite'
+import polka from 'polka'
+import sirv from 'sirv'
+import * as headers from './headers'
+
+const fallback = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <!-- ssr:head -->
+</head>
+<body>
+  <!-- ssr:data -->
+  <div id="root"><!-- ssr:root --></div>
+  <script src="/src/client" type="module"></script>
+</body>
+</html>`
+
+const markers = /<!--\s*ssr:([A-Za-z0-9_]+)\s*-->/g
+
+/** Compiles an HTML file with ssr:* comments into a slot renderer. */
+export function compile(html: string) {
+
+	const parts = html.split(markers)
+
+	return (slots: Record<string, string>) =>
+		parts.map((part, index) => index % 2 ? slots[part] ?? '' : part).join('')
+}
+
+async function html() {
+	try { return await fs.readFile('./index.html', 'utf-8') }
+	catch { return fallback }
+}
+
+/** Development server options accepted by dev(). */
+export type Options = {
+	hmr?: vite.ServerOptions['hmr']
+}
+
+/** Creates the development Polka app with Vite middleware and route reloads. */
+export async function dev(options: Options = {}) {
+
+	const app = polka()
+
+	const server = await vite.createServer({
+		server: { middlewareMode: true, ...(options.hmr !== undefined && { hmr: options.hmr }) },
+		appType: 'custom',
+	})
+
+	app.use(server.middlewares)
+
+	let raw = await html()
+	raw = await server.transformIndexHtml('/', raw)
+	const template = compile(raw)
+
+	const { create } = await server.ssrLoadModule('ajo-kit/server')
+	let inner = await create(template)
+
+	app.use((req: any, res: any) => inner.handler(req, res))
+
+	const route = /(handler|wares|page|layout)\.[jt]sx?$/
+	const reload = async (file: string) => {
+		if (!route.test(file)) return
+		try {
+			const { create } = await server.ssrLoadModule('ajo-kit/server')
+			inner = await create(template)
+			console.log('\x1b[32m✓\x1b[0m Server routes reloaded')
+			if (/(page|layout)\.[jt]sx?$/.test(file)) server.ws.send({ type: 'full-reload', path: '*' })
+		} catch (error) {
+			console.error('\x1b[31m✗\x1b[0m Failed to reload routes:')
+			console.error(error)
+		}
+	}
+
+	server.watcher.on('change', reload)
+	server.watcher.on('add', reload)
+	server.watcher.on('unlink', reload)
+
+	return app
+}
+
+/** Creates the production Polka app from dist/client and dist/server. */
+export async function start() {
+
+	const app = polka()
+
+	const entry = url.pathToFileURL(join(process.cwd(), 'dist/server/server.js')).href
+	const { create } = await import(entry)
+
+	const inner = await create(compile(await fs.readFile(join(process.cwd(), 'dist/client/index.html'), 'utf-8')))
+
+	app.use(sirv(join(process.cwd(), 'dist/client'), {
+		extensions: [],
+		setHeaders: res => headers.set(res, headers.security(), true),
+	}))
+	app.use((req: any, res: any) => inner.handler(req, res))
+
+	return app
+}
+
+/** Builds client and server bundles into dist/. */
+export async function build() {
+
+	await vite.build({ build: { outDir: 'dist/client' } })
+
+	const entry = url.fileURLToPath(import.meta.resolve('ajo-kit/server'))
+
+	await vite.build({
+		build: {
+			outDir: 'dist/server',
+			ssr: entry,
+			rollupOptions: { output: { entryFileNames: 'server.js' } },
+		}
+	})
+}
+
+/** Starts an app, incrementing the port when it is busy unless strict is set. */
+export const listen = (app: any, port = 5173, options: { strict?: boolean } = {}): Promise<number> => new Promise((resolve, reject) => {
+	http.createServer(app.handler)
+		.listen(port, () => {
+			console.log(`Server started at http://localhost:${port}`)
+			resolve(port)
+		})
+		.once('error', (error: NodeJS.ErrnoException) =>
+			error.code === 'EADDRINUSE' && !options.strict
+				? resolve(listen(app, port + 1, options))
+				: reject(error)
+		)
+})