@jant/core 0.0.1

package/src/i18n/locales/zh-Hant.ts

@@ -0,0 +1 @@
+/*eslint-disable*/import type{Messages}from"@lingui/core";export const messages=JSON.parse("{\"+7Wr2a\":[\"編輯: \",[\"title\"]],\"+MACwa\":[\"尚未有任何收藏。\"],\"+owNNn\":[\"文章\"],\"+zy2Nq\":[\"類型\"],\"/0D1Xp\":[\"編輯收藏集\"],\"/Rj5P4\":[\"您的姓名\"],\"0JkyS7\":[\"建立您的第一個頁面\"],\"0a6MpL\":[\"新重定向\"],\"1CU1Td\":[\"網址安全識別碼（小寫、數字、連字符）\"],\"1DBGsz\":[\"筆記\"],\"2N0qpv\":[\"文章標題...\"],\"2q/Q7x\":[\"可見性\"],\"2rJGtU\":[\"頁面標題...\"],\"3Yvsaz\":[\"302（臨時）\"],\"4/SFQS\":[\"查看網站\"],\"40TVQj\":[\"自訂路徑（選填）\"],\"4KzVT6\":[\"刪除頁面\"],\"4b3oEV\":[\"內容\"],\"4mDPGp\":[\"此頁面的 URL 路徑。使用小寫字母、數字和連字符。\"],\"6WdDG7\":[\"頁面\"],\"7G4SBz\":[\"頁面內容（支持Markdown）...\"],\"7Mk+/h\":[\"更新收藏集\"],\"7Q1KKN\":[\"來源路徑\"],\"7nGhhM\":[\"你在想什麼？\"],\"7p5kLi\":[\"儀表板\"],\"8ZsakT\":[\"密碼\"],\"90Luob\":[[\"count\"],\" 條回覆\"],\"A1taO8\":[\"搜尋\"],\"AyHO4m\":[\"這個收藏是關於什麼的？\"],\"B373X+\":[\"編輯文章\"],\"B495Gs\":[\"檔案館\"],\"BjF0Jv\":[\"僅限小寫字母、數字和連字符\"],\"D9Oea+\":[\"永久鏈接\"],\"DHhJ7s\":[\"上一頁\"],\"DoJzLz\":[\"收藏夾\"],\"E80cJw\":[\"刪除此媒體將永久從存儲中移除它。\"],\"EEYbdt\":[\"發佈\"],\"EGwzOK\":[\"完成設置\"],\"EkH9pt\":[\"更新\"],\"FGrimz\":[\"新帖子\"],\"FkMol5\":[\"精選\"],\"Fxf4jq\":[\"描述（可選）\"],\"GA5A5H\":[\"刪除收藏夾\"],\"GorKul\":[\"歡迎來到 Jant\"],\"GrZ6fH\":[\"新頁面\"],\"HfyyXl\":[\"我的部落格\"],\"HiETwV\":[\"安靜（正常）\"],\"Hzi9AA\":[\"未找到任何帖子。\"],\"I6gXOa\":[\"路徑\"],\"IagCbF\":[\"網址\"],\"J4FNfC\":[\"此集合中沒有帖子。\"],\"JIBC/T\":[\"支援的格式：JPEG、PNG、GIF、WebP、SVG。最大大小：10MB。\"],\"JiP4aa\":[\"已發佈的頁面可以通過其路徑訪問。草稿不可見。\"],\"K9NcLu\":[\"使用此 URL 將媒體嵌入到您的帖子中。\"],\"KiJn9B\":[\"備註\"],\"L85WcV\":[\"縮略名\"],\"LkvLQe\":[\"尚未有頁面。\"],\"M8kJqa\":[\"草稿\"],\"M9xgHy\":[\"重定向\"],\"MHrjPM\":[\"標題\"],\"MZbQHL\":[\"未找到結果。\"],\"Mhf/H/\":[\"建立重定向\"],\"MqghUt\":[\"搜尋帖子...\"],\"N40H+G\":[\"所有\"],\"O3oNi5\":[\"電子郵件\"],\"OCNZaU\":[\"重定向來源的路徑\"],\"ODiSoW\":[\"尚未有帖子。\"],\"ONWvwQ\":[\"上傳\"],\"Pbm2/N\":[\"創建收藏夾\"],\"RDjuBN\":[\"設置\"],\"Rj01Fz\":[\"連結\"],\"RwGhWy\":[\"包含 \",[\"count\"],\" 則帖子的主題\"],\"SJmfuf\":[\"網站名稱\"],\"ST+lN2\":[\"尚未上傳任何媒體。\"],\"Tt5T6+\":[\"文章\"],\"TxE+Mj\":[\"1 條回覆\"],\"Tz0i8g\":[\"設定\"],\"U5v6Gh\":[\"編輯頁面\"],\"UDMjsP\":[\"快速操作\"],\"UGT5vp\":[\"保存設定\"],\"VUSy8D\":[\"搜尋失敗。請再試一次。\"],\"WDcQq9\":[\"不公開\"],\"Weq9zb\":[\"一般設定\"],\"WmZ/rP\":[\"到路徑\"],\"Y+7JGK\":[\"創建頁面\"],\"ZQKLI1\":[\"危險區域\"],\"ZhhOwV\":[\"引用\"],\"an5hVd\":[\"圖片\"],\"b+/jO6\":[\"301（永久）\"],\"bHYIks\":[\"登出\"],\"biOepV\":[\"← 返回首頁\"],\"cnGeoo\":[\"刪除\"],\"dEgA5A\":[\"取消\"],\"e6Jr7Q\":[\"← 返回收藏夾\"],\"ePK91l\":[\"編輯\"],\"eWLklq\":[\"引用\"],\"eneWvv\":[\"草稿\"],\"f6e0Ry\":[\"文章\"],\"fG7BxZ\":[\"透過 API 上傳圖片：POST /api/upload，並使用文件表單字段。\"],\"fttd2R\":[\"我的收藏\"],\"hG89Ed\":[\"圖片\"],\"hXzOVo\":[\"下一頁\"],\"he3ygx\":[\"複製\"],\"iH8pgl\":[\"返回\"],\"ig4hg2\":[\"讓我們設置您的網站。\"],\"jpctdh\":[\"查看\"],\"mTOYla\":[\"查看所有文章 →\"],\"n1ekoW\":[\"登入\"],\"oYPBa0\":[\"更新頁面\"],\"pRhYH2\":[\"收藏中的帖子 (\",[\"count\"],\")\"],\"qMyM2u\":[\"來源網址（選填）\"],\"r1MpXi\":[\"安靜\"],\"rdUucN\":[\"預覽\"],\"rzNUSl\":[\"包含 1 則貼文的主題\"],\"sGajR7\":[\"線程開始\"],\"t/YqKh\":[\"移除\"],\"tfrt7B\":[\"未配置任何重定向。\"],\"tiq7kl\":[\"頁面 \",[\"page\"]],\"u2f7vd\":[\"網站描述\"],\"u3wRF+\":[\"已發佈\"],\"u6Hp4N\":[\"Markdown\"],\"uAQUqI\":[\"狀態\"],\"vXIe7J\":[\"語言\"],\"vzU4k9\":[\"新收藏集\"],\"wEF6Ix\":[\"目的地路徑或 URL\"],\"wK4OTM\":[\"標題（選填）\"],\"wM5UXj\":[\"刪除媒體\"],\"wRR604\":[\"頁面\"],\"wja8aL\":[\"無標題\"],\"x0mzE0\":[\"創建你的第一篇帖子\"],\"x4RuFo\":[\"回到首頁\"],\"xYilR2\":[\"媒體\"],\"y28hnO\":[\"文章\"],\"yQ2kGp\":[\"載入更多\"],\"yzF66j\":[\"連結\"],\"z8ajIE\":[\"找到 1 個結果\"],\"zH6KqE\":[\"找到 \",[\"count\"],\" 個結果\"]}")as Messages;

package/src/i18n/locales.ts

@@ -0,0 +1,14 @@
+/**
+ * Centralized locale configuration
+ */
+
+export const locales = ["en", "zh-Hans", "zh-Hant"] as const;
+export type Locale = (typeof locales)[number];
+export const baseLocale: Locale = "en";
+
+/**
+ * Check if a value is a valid locale
+ */
+export function isLocale(value: unknown): value is Locale {
+  return typeof value === "string" && locales.includes(value as Locale);
+}

package/src/i18n/middleware.ts

@@ -0,0 +1,59 @@
+/**
+ * i18n Hono Middleware
+ */
+
+import type { MiddlewareHandler } from "hono";
+import type { I18n } from "@lingui/core";
+import { detectLanguage } from "./detect.js";
+import { createI18n, isLocale, type Locale } from "./i18n.js";
+import type { Services } from "../services/index.js";
+
+declare module "hono" {
+  interface ContextVariableMap {
+    lang: Locale;
+    i18n: I18n;
+  }
+}
+
+/**
+ * Hono middleware for internationalization.
+ * Creates a per-request i18n instance to avoid race conditions in concurrent environments.
+ *
+ * Language detection priority:
+ * 1. Cookie (user preference)
+ * 2. Database SITE_LANGUAGE setting (site default)
+ * 3. Accept-Language header
+ * 4. Default locale (en)
+ */
+export function i18nMiddleware(): MiddlewareHandler {
+  return async (c, next) => {
+    // First try cookie and Accept-Language header
+    let lang = detectLanguage(c);
+
+    // If no cookie is set, check database SITE_LANGUAGE setting
+    const cookies = c.req.raw.headers.get("Cookie") ?? "";
+    const hasCookie = cookies.includes("lang=");
+
+    if (!hasCookie) {
+      // Check database setting
+      const services = c.get("services") as Services | undefined;
+      if (services) {
+        try {
+          const siteLang = await services.settings.get("SITE_LANGUAGE");
+          if (siteLang && isLocale(siteLang)) {
+            lang = siteLang;
+          }
+        } catch {
+          // Ignore errors, fall back to detected language
+        }
+      }
+    }
+
+    // Create a new i18n instance for this request to avoid race conditions
+    const i18n = createI18n(lang);
+
+    c.set("lang", lang);
+    c.set("i18n", i18n);
+    await next();
+  };
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Jant - A microblog system
+ *
+ * @packageDocumentation
+ */
+
+import { createApp as _createApp } from "./app.js";
+
+// Main app factory
+export { createApp } from "./app.js";
+export type { App, AppVariables } from "./app.js";
+
+// Types (excluding component props to avoid conflicts with theme exports)
+export type {
+  PostType,
+  Visibility,
+  Bindings,
+  Post,
+  Media,
+  Collection,
+  PostCollection,
+  Redirect,
+  Setting,
+  CreatePost,
+  UpdatePost,
+  JantConfig,
+  JantTheme,
+  SiteConfig,
+  FeatureConfig,
+  ThemeComponents,
+} from "./types.js";
+
+export { POST_TYPES, VISIBILITY_LEVELS } from "./types.js";
+
+// Utilities (for theme authors)
+export * as time from "./lib/time.js";
+export * as sqid from "./lib/sqid.js";
+export * as url from "./lib/url.js";
+export * as markdown from "./lib/markdown.js";
+
+// Default export for running core directly (e.g., for development)
+export default _createApp();

package/src/lib/assets.ts

@@ -0,0 +1,47 @@
+/**
+ * Asset paths for SSR
+ *
+ * Development: Uses source paths served by Vite dev server
+ * Production: Uses paths that get patched at build time with actual hashes
+ */
+
+interface Assets {
+  styles: string;
+  client: string;
+  datastar: string;
+  imageProcessor: string;
+}
+
+// Development paths
+const DEV_ASSETS: Assets = {
+  styles: "/node_modules/@jant/core/src/theme/styles/main.css",
+  client: "/node_modules/@jant/core/src/client.ts",
+  datastar: "/node_modules/@jant/core/static/assets/datastar.min.js",
+  imageProcessor: "/node_modules/@jant/core/static/assets/image-processor.js",
+};
+
+// Production paths - these unique placeholders get replaced at build time
+// Format: __JANT_ASSET_<NAME>__ to avoid accidental matches
+const PROD_ASSETS: Assets = {
+  styles: "__JANT_ASSET_STYLES__",
+  client: "__JANT_ASSET_CLIENT__",
+  datastar: "__JANT_ASSET_DATASTAR__",
+  imageProcessor: "__JANT_ASSET_IMAGE_PROCESSOR__",
+};
+
+/**
+ * Get assets based on environment
+ */
+export function getAssets(): Assets {
+  try {
+    // import.meta.env is injected by Vite
+    if (import.meta.env?.DEV) return DEV_ASSETS;
+  } catch {
+    // import.meta.env may not exist in all environments
+  }
+
+  return PROD_ASSETS;
+}
+
+// For static imports
+export const ASSETS = PROD_ASSETS;

package/src/lib/constants.ts

@@ -0,0 +1,67 @@
+/**
+ * Application Constants
+ */
+
+/**
+ * Reserved URL paths that cannot be used for pages
+ */
+export const RESERVED_PATHS = [
+  "featured",
+  "signin",
+  "signout",
+  "setup",
+  "dash",
+  "api",
+  "feed",
+  "search",
+  "archive",
+  "notes",
+  "articles",
+  "links",
+  "quotes",
+  "media",
+  "pages",
+  "p",
+  "c",
+  "static",
+  "assets",
+  "health",
+] as const;
+
+export type ReservedPath = (typeof RESERVED_PATHS)[number];
+
+/**
+ * Check if a path is reserved
+ */
+export function isReservedPath(path: string): boolean {
+  const firstSegment = path.split("/")[0]?.toLowerCase();
+  return RESERVED_PATHS.includes(firstSegment as ReservedPath);
+}
+
+/**
+ * Default pagination size
+ */
+export const DEFAULT_PAGE_SIZE = 100;
+
+/**
+ * Settings keys (match environment variable naming)
+ */
+export const SETTINGS_KEYS = {
+  ONBOARDING_STATUS: "ONBOARDING_STATUS",
+  SITE_NAME: "SITE_NAME",
+  SITE_DESCRIPTION: "SITE_DESCRIPTION",
+  SITE_LANGUAGE: "SITE_LANGUAGE",
+  THEME: "THEME",
+} as const;
+
+export type SettingsKey = (typeof SETTINGS_KEYS)[keyof typeof SETTINGS_KEYS];
+
+/**
+ * Onboarding status values
+ */
+export const ONBOARDING_STATUS = {
+  PENDING: "pending",
+  COMPLETED: "completed",
+} as const;
+
+export type OnboardingStatus = (typeof ONBOARDING_STATUS)[keyof typeof ONBOARDING_STATUS];

package/src/lib/image.ts

@@ -0,0 +1,107 @@
+/**
+ * Image URL utilities
+ *
+ * Provides helpers for generating image URLs with optional transformations.
+ */
+
+/**
+ * Options for image transformations
+ */
+export interface ImageOptions {
+  /** Target width in pixels */
+  width?: number;
+  /** Target height in pixels */
+  height?: number;
+  /** Quality (1-100) */
+  quality?: number;
+  /** Output format */
+  format?: "webp" | "avif" | "auto";
+  /** Fit mode for resizing */
+  fit?: "cover" | "contain" | "scale-down";
+}
+
+/**
+ * Generates an image URL with optional transformations.
+ *
+ * If `transformUrl` is provided and options are specified, returns a transformed image URL.
+ * Otherwise, returns the original URL unchanged.
+ *
+ * Compatible with:
+ * - Cloudflare Image Transformations (`/cdn-cgi/image/...`)
+ * - imgproxy
+ * - Cloudinary
+ * - Any service with similar URL-based transformation API
+ *
+ * @param originalUrl - The original image URL
+ * @param transformUrl - The base URL for transformations (e.g., `https://example.com/cdn-cgi/image`)
+ * @param options - Transformation options (width, height, quality, format, fit)
+ * @returns The transformed URL or original URL if transformations are not configured
+ *
+ * @example
+ * ```ts
+ * // Without transform URL - returns original
+ * getImageUrl("/media/abc123", undefined, { width: 200 });
+ * // Returns: "/media/abc123"
+ *
+ * // With transform URL - returns transformed
+ * getImageUrl("/media/abc123", "https://example.com/cdn-cgi/image", { width: 200, quality: 80 });
+ * // Returns: "https://example.com/cdn-cgi/image/width=200,quality=80/https://example.com/media/abc123"
+ * ```
+ */
+export function getImageUrl(
+  originalUrl: string,
+  transformUrl?: string,
+  options?: ImageOptions
+): string {
+  if (!transformUrl || !options || Object.keys(options).length === 0) {
+    return originalUrl;
+  }
+
+  const params: string[] = [];
+  if (options.width) params.push(`width=${options.width}`);
+  if (options.height) params.push(`height=${options.height}`);
+  if (options.quality) params.push(`quality=${options.quality}`);
+  if (options.format) params.push(`format=${options.format}`);
+  if (options.fit) params.push(`fit=${options.fit}`);
+
+  if (params.length === 0) {
+    return originalUrl;
+  }
+
+  return `${transformUrl}/${params.join(",")}/${originalUrl}`;
+}
+
+/**
+ * Generates a media URL using UUIDv7-based paths.
+ *
+ * Returns a public URL for a media file. If `r2PublicUrl` is set, uses that directly
+ * with the r2Key. Otherwise, generates a `/media/{id}.{ext}` URL.
+ *
+ * @param mediaId - The UUIDv7 database ID of the media
+ * @param r2Key - The R2 storage key (used to extract extension)
+ * @param r2PublicUrl - Optional R2 public URL for direct CDN access
+ * @returns The public URL for the media file
+ *
+ * @example
+ * ```ts
+ * // Without R2 public URL - uses UUID with extension
+ * getMediaUrl("01902a9f-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "uploads/file.webp");
+ * // Returns: "/media/01902a9f-1a2b-7c3d-8e4f-5a6b7c8d9e0f.webp"
+ *
+ * // With R2 public URL - uses direct CDN
+ * getMediaUrl("01902a9f-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "uploads/file.webp", "https://cdn.example.com");
+ * // Returns: "https://cdn.example.com/uploads/file.webp"
+ * ```
+ */
+export function getMediaUrl(
+  mediaId: string,
+  r2Key: string,
+  r2PublicUrl?: string
+): string {
+  if (r2PublicUrl) {
+    return `${r2PublicUrl}/${r2Key}`;
+  }
+  // Extract extension from r2Key
+  const ext = r2Key.split(".").pop() || "bin";
+  return `/media/${mediaId}.${ext}`;
+}

package/src/lib/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Utility Functions
+ */
+
+export * from "./constants.js";
+export * as sqid from "./sqid.js";
+export * as time from "./time.js";
+export * as url from "./url.js";
+export * as markdown from "./markdown.js";

package/src/lib/markdown.ts

@@ -0,0 +1,93 @@
+/**
+ * Markdown Rendering
+ *
+ * Uses marked with minimal configuration
+ */
+
+import { marked } from "marked";
+
+// Configure marked for security and simplicity
+marked.setOptions({
+  gfm: true,
+  breaks: true,
+});
+
+/**
+ * Renders Markdown content to HTML using the marked library.
+ *
+ * Configured with GitHub Flavored Markdown (GFM) support and line breaks enabled.
+ * Uses synchronous parsing for simplicity and consistency in server-side rendering.
+ *
+ * @param markdown - The Markdown string to convert to HTML
+ * @returns The rendered HTML string
+ *
+ * @example
+ * ```ts
+ * const html = render("# Hello\n\nThis is **bold** text.");
+ * // Returns: "<h1>Hello</h1>\n<p>This is <strong>bold</strong> text.</p>"
+ * ```
+ */
+export function render(markdown: string): string {
+  return marked.parse(markdown, { async: false }) as string;
+}
+
+/**
+ * Converts Markdown to plain text by stripping all formatting syntax.
+ *
+ * Removes Markdown syntax including headers, bold, italic, links, images, code blocks,
+ * blockquotes, lists, and converts newlines to spaces. Useful for generating text excerpts,
+ * meta descriptions, or search indexes.
+ *
+ * @param markdown - The Markdown string to convert to plain text
+ * @returns The plain text string with all Markdown syntax removed
+ *
+ * @example
+ * ```ts
+ * const plain = toPlainText("## Hello\n\nThis is **bold** and [a link](url).");
+ * // Returns: "Hello This is bold and a link."
+ * ```
+ */
+export function toPlainText(markdown: string): string {
+  return markdown
+    .replace(/#{1,6}\s+/g, "") // Remove headers
+    .replace(/\*\*(.+?)\*\*/g, "$1") // Bold
+    .replace(/\*(.+?)\*/g, "$1") // Italic
+    .replace(/\[(.+?)\]\(.+?\)/g, "$1") // Links
+    .replace(/!\[.*?\]\(.+?\)/g, "") // Images
+    .replace(/`{1,3}[^`]*`{1,3}/g, "") // Code
+    .replace(/>\s+/g, "") // Blockquotes
+    .replace(/[-*+]\s+/g, "") // Lists
+    .replace(/\n+/g, " ") // Newlines
+    .trim();
+}
+
+/**
+ * Extracts a title from Markdown content by taking the first sentence or line.
+ *
+ * Converts Markdown to plain text first, then takes the first sentence (split by `.!?`)
+ * or truncates to the specified maximum length. Useful for generating automatic titles
+ * from post content when no explicit title is provided.
+ *
+ * @param markdown - The Markdown string to extract a title from
+ * @param maxLength - Maximum length of the extracted title (default: 120)
+ * @returns The extracted title string, with "..." appended if truncated
+ *
+ * @example
+ * ```ts
+ * const title = extractTitle("This is the first sentence. And another one.", 50);
+ * // Returns: "This is the first sentence"
+ *
+ * const title = extractTitle("A very long sentence that exceeds the maximum length...", 30);
+ * // Returns: "A very long sentence that ex..."
+ * ```
+ */
+export function extractTitle(markdown: string, maxLength = 120): string {
+  const plain = toPlainText(markdown);
+  const firstLine = plain.split(/[.!?]/)[0] ?? plain;
+
+  if (firstLine.length <= maxLength) {
+    return firstLine;
+  }
+
+  return plain.slice(0, maxLength).trim() + "...";
+}

package/src/lib/schemas.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared Zod schemas for validation
+ *
+ * These schemas ensure type-safe validation of user input
+ * from forms, API requests, and other external sources.
+ *
+ * IMPORTANT: Types are defined in types.ts as the single source of truth.
+ * This file only defines Zod validation schemas based on those types.
+ */
+
+import { z } from "zod";
+import { POST_TYPES, VISIBILITY_LEVELS } from "../types.js";
+
+/**
+ * Post type enum schema
+ * Based on POST_TYPES from types.ts
+ */
+export const PostTypeSchema = z.enum(POST_TYPES);
+
+/**
+ * Visibility enum schema
+ * Based on VISIBILITY_LEVELS from types.ts
+ */
+export const VisibilitySchema = z.enum(VISIBILITY_LEVELS);
+
+/**
+ * Redirect type enum schema
+ * Form input validation for redirect type (stored as number in DB)
+ */
+export const RedirectTypeSchema = z.enum(["301", "302"]);
+
+/**
+ * API request body schema for creating a post
+ */
+export const CreatePostSchema = z.object({
+  type: PostTypeSchema,
+  title: z.string().optional(),
+  content: z.string(),
+  visibility: VisibilitySchema,
+  sourceUrl: z.string().url().optional().or(z.literal("")),
+  sourceName: z.string().optional(),
+  path: z.string().regex(/^[a-z0-9-]*$/).optional().or(z.literal("")),
+  replyToId: z.string().optional(), // Sqid format
+  publishedAt: z.number().int().positive().optional(),
+});
+
+/**
+ * API request body schema for updating a post
+ */
+export const UpdatePostSchema = CreatePostSchema.partial();
+
+/**
+ * Form data helper: safely parse a FormData value with a schema
+ *
+ * @example
+ * ```ts
+ * const type = parseFormData(formData, "type", PostTypeSchema);
+ * // type is PostType, throws if invalid
+ * ```
+ */
+export function parseFormData<T>(
+  formData: FormData,
+  key: string,
+  schema: z.ZodSchema<T>
+): T {
+  const value = formData.get(key);
+  if (value === null) {
+    throw new Error(`Missing required field: ${key}`);
+  }
+  return schema.parse(value);
+}
+
+/**
+ * Form data helper: safely parse optional FormData value with a schema
+ *
+ * @example
+ * ```ts
+ * const slug = parseFormDataOptional(formData, "slug", z.string());
+ * // slug is string | undefined
+ * ```
+ */
+export function parseFormDataOptional<T>(
+  formData: FormData,
+  key: string,
+  schema: z.ZodSchema<T>
+): T | undefined {
+  const value = formData.get(key);
+  if (value === null || value === "") {
+    return undefined;
+  }
+  return schema.parse(value);
+}

package/src/lib/sqid.ts

@@ -0,0 +1,79 @@
+/**
+ * Sqids - Short unique IDs for URLs
+ *
+ * Encodes numeric IDs to short strings like "jR3k"
+ */
+
+import Sqids from "sqids";
+
+const sqids = new Sqids({
+  minLength: 4,
+});
+
+/**
+ * Encodes a numeric database ID to a short, URL-friendly string.
+ *
+ * Uses the Sqids library to generate short unique identifiers with a minimum length of 4 characters.
+ * These are used in URLs (e.g., `/p/jR3k`) to obscure sequential integer IDs while maintaining
+ * uniqueness and reversibility.
+ *
+ * @param id - The numeric database ID to encode
+ * @returns A short string representation of the ID (minimum 4 characters)
+ *
+ * @example
+ * ```ts
+ * const sqid = encode(123);
+ * // Returns: "jR3k" (or similar short string)
+ * ```
+ */
+export function encode(id: number): string {
+  return sqids.encode([id]);
+}
+
+/**
+ * Decodes a sqid string back to the original numeric database ID.
+ *
+ * Attempts to decode a sqid string generated by the `encode()` function. Returns the original
+ * numeric ID if valid, or `null` if the string is not a valid sqid. This is used to extract
+ * database IDs from URL parameters.
+ *
+ * @param str - The sqid string to decode
+ * @returns The original numeric ID if valid, or `null` if decoding fails
+ *
+ * @example
+ * ```ts
+ * const id = decode("jR3k");
+ * // Returns: 123
+ *
+ * const invalid = decode("invalid");
+ * // Returns: null
+ * ```
+ */
+export function decode(str: string): number | null {
+  try {
+    const ids = sqids.decode(str);
+    return ids[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Checks if a string is a valid sqid that can be decoded.
+ *
+ * Validates whether a string can be successfully decoded to a numeric ID.
+ * Useful for route validation and input sanitization.
+ *
+ * @param str - The string to validate
+ * @returns `true` if the string is a valid sqid, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * if (isValidSqid("jR3k")) {
+ *   // Process the valid sqid
+ * }
+ * ```
+ */
+export function isValidSqid(str: string): boolean {
+  return decode(str) !== null;
+}