@jant/core 0.0.1

package/src/lib/sse.ts

@@ -0,0 +1,152 @@
+/**
+ * Server-Sent Events (SSE) utilities for Datastar
+ *
+ * Provides helpers for streaming SSE responses that Datastar can consume.
+ * Datastar uses SSE for real-time UI updates without page reloads.
+ *
+ * @see https://data-star.dev/
+ *
+ * @example
+ * ```ts
+ * app.post("/api/example", (c) => {
+ *   return sse(c, async (stream) => {
+ *     await stream.patchSignals({ loading: false });
+ *     await stream.patchElements("#result", "<div>Done!</div>");
+ *   });
+ * });
+ * ```
+ */
+
+import type { Context } from "hono";
+
+/**
+ * Patch modes for DOM updates
+ */
+export type PatchMode = "morph" | "inner" | "outer" | "append" | "prepend" | "remove";
+
+/**
+ * SSE stream writer for Datastar events
+ */
+export interface SSEStream {
+  /**
+   * Update reactive signals on the client
+   *
+   * @param signals - Object containing signal values to update
+   *
+   * @example
+   * ```ts
+   * await stream.patchSignals({ count: 42, loading: false });
+   * ```
+   */
+  patchSignals(signals: Record<string, unknown>): Promise<void>;
+
+  /**
+   * Update DOM elements
+   *
+   * @param html - HTML content (must include element with id for targeting)
+   * @param options - Optional mode and selector
+   *
+   * @example
+   * ```ts
+   * // Replace element with matching id (default: morph)
+   * await stream.patchElements('<div id="content">New content</div>');
+   *
+   * // Append to a container
+   * await stream.patchElements('<div>New item</div>', {
+   *   mode: 'append',
+   *   selector: '#list'
+   * });
+   * ```
+   */
+  patchElements(
+    html: string,
+    options?: { mode?: PatchMode; selector?: string }
+  ): Promise<void>;
+
+  /**
+   * Execute JavaScript on the client
+   *
+   * @param script - JavaScript code to execute
+   *
+   * @example
+   * ```ts
+   * await stream.executeScript('console.log("Hello from server")');
+   * ```
+   */
+  executeScript(script: string): Promise<void>;
+}
+
+/**
+ * Create an SSE response for Datastar
+ *
+ * @param c - Hono context
+ * @param handler - Async function that writes to the SSE stream
+ * @returns Response with SSE content-type
+ *
+ * @example
+ * ```ts
+ * app.post("/api/upload", (c) => {
+ *   return sse(c, async (stream) => {
+ *     // Process upload...
+ *     await stream.patchSignals({ uploading: false });
+ *     await stream.patchElements('<div id="new-item">...</div>', {
+ *       mode: 'append',
+ *       selector: '#items'
+ *     });
+ *   });
+ * });
+ * ```
+ */
+export function sse(
+  c: Context,
+  handler: (stream: SSEStream) => Promise<void>
+): Response {
+  const encoder = new TextEncoder();
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      const write = (data: string) => {
+        controller.enqueue(encoder.encode(data));
+      };
+
+      const sseStream: SSEStream = {
+        async patchSignals(signals) {
+          write(`event: datastar-patch-signals\n`);
+          write(`data: signals ${JSON.stringify(signals)}\n\n`);
+        },
+
+        async patchElements(html, options = {}) {
+          write(`event: datastar-patch-elements\n`);
+          if (options.mode) {
+            write(`data: mode ${options.mode}\n`);
+          }
+          if (options.selector) {
+            write(`data: selector ${options.selector}\n`);
+          }
+          // Escape newlines in HTML for SSE format
+          const escapedHtml = html.replace(/\n/g, "\ndata: ");
+          write(`data: elements ${escapedHtml}\n\n`);
+        },
+
+        async executeScript(script) {
+          write(`event: datastar-execute-script\n`);
+          write(`data: script ${script}\n\n`);
+        },
+      };
+
+      try {
+        await handler(sseStream);
+      } finally {
+        controller.close();
+      }
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+    },
+  });
+}

package/src/lib/time.ts

@@ -0,0 +1,117 @@
+/**
+ * Time Utilities
+ */
+
+/**
+ * Gets the current Unix timestamp in seconds.
+ *
+ * Returns the number of seconds since the Unix epoch (January 1, 1970 00:00:00 UTC).
+ * This is the standard time format used throughout the application for consistency
+ * and database storage.
+ *
+ * @returns Current Unix timestamp in seconds (not milliseconds)
+ *
+ * @example
+ * ```ts
+ * const timestamp = now();
+ * // Returns: 1706745600 (example value for Feb 1, 2024)
+ * ```
+ */
+export function now(): number {
+  return Math.floor(Date.now() / 1000);
+}
+
+/**
+ * One month in seconds
+ */
+const ONE_MONTH = 30 * 24 * 60 * 60;
+
+/**
+ * Checks if a Unix timestamp is within the last 30 days.
+ *
+ * Compares the given timestamp to the current time to determine if it falls within
+ * the last month (defined as 30 days). Useful for highlighting recent posts or
+ * filtering time-sensitive content.
+ *
+ * @param timestamp - Unix timestamp in seconds to check
+ * @returns `true` if the timestamp is within the last 30 days, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * const recentPost = 1706745600;  // Recent timestamp
+ * if (isWithinMonth(recentPost)) {
+ *   // Show "new" badge
+ * }
+ * ```
+ */
+export function isWithinMonth(timestamp: number): boolean {
+  return now() - timestamp < ONE_MONTH;
+}
+
+/**
+ * Converts a Unix timestamp to an ISO 8601 date-time string.
+ *
+ * Formats a Unix timestamp (in seconds) as an ISO 8601 string suitable for HTML
+ * `datetime` attributes and API responses. The output includes full date, time,
+ * and timezone information in UTC.
+ *
+ * @param timestamp - Unix timestamp in seconds to convert
+ * @returns ISO 8601 formatted string (e.g., "2024-02-01T12:00:00.000Z")
+ *
+ * @example
+ * ```ts
+ * const isoDate = toISOString(1706745600);
+ * // Returns: "2024-02-01T00:00:00.000Z"
+ * ```
+ */
+export function toISOString(timestamp: number): string {
+  return new Date(timestamp * 1000).toISOString();
+}
+
+/**
+ * Formats a Unix timestamp as a human-readable date string.
+ *
+ * Converts a Unix timestamp (in seconds) to a localized date string in the format
+ * "MMM DD, YYYY" (e.g., "Jan 15, 2024"). Always uses UTC timezone to ensure
+ * consistent display regardless of server or client location.
+ *
+ * @param timestamp - Unix timestamp in seconds to format
+ * @returns Formatted date string in "MMM DD, YYYY" format
+ *
+ * @example
+ * ```ts
+ * const readable = formatDate(1706745600);
+ * // Returns: "Feb 1, 2024"
+ * ```
+ */
+export function formatDate(timestamp: number): string {
+  return new Date(timestamp * 1000).toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    timeZone: "UTC",
+  });
+}
+
+/**
+ * Formats a Unix timestamp as a year-month string for grouping.
+ *
+ * Converts a Unix timestamp (in seconds) to a "YYYY-MM" format string, useful for
+ * grouping posts by month in archives or creating month-based URLs. Always uses
+ * UTC timezone for consistency.
+ *
+ * @param timestamp - Unix timestamp in seconds to format
+ * @returns Year-month string in "YYYY-MM" format
+ *
+ * @example
+ * ```ts
+ * const yearMonth = formatYearMonth(1706745600);
+ * // Returns: "2024-02"
+ * ```
+ */
+export function formatYearMonth(timestamp: number): string {
+  const date = new Date(timestamp * 1000);
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  return `${year}-${month}`;
+}

package/src/lib/url.ts

@@ -0,0 +1,107 @@
+/**
+ * URL Utilities
+ */
+
+/**
+ * Extracts the hostname (domain) from a URL string.
+ *
+ * Parses a full URL and returns just the hostname portion (e.g., "example.com" from
+ * "https://example.com/path"). Returns `null` if the URL is malformed or cannot be parsed.
+ *
+ * @param url - The full URL string to extract the domain from
+ * @returns The hostname/domain if valid, or `null` if parsing fails
+ *
+ * @example
+ * ```ts
+ * const domain = extractDomain("https://www.example.com/path");
+ * // Returns: "www.example.com"
+ *
+ * const invalid = extractDomain("not-a-url");
+ * // Returns: null
+ * ```
+ */
+export function extractDomain(url: string): string | null {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Normalizes a path by removing slashes and converting to lowercase.
+ *
+ * Trims whitespace, converts to lowercase, removes leading and trailing slashes,
+ * and collapses multiple consecutive slashes into single slashes. Used to create
+ * consistent path representations for routing and storage.
+ *
+ * @param path - The path string to normalize
+ * @returns The normalized path string
+ *
+ * @example
+ * ```ts
+ * const normalized = normalizePath("  /About/Contact//  ");
+ * // Returns: "about/contact"
+ * ```
+ */
+export function normalizePath(path: string): string {
+  return path
+    .trim()
+    .toLowerCase()
+    .replace(/^\/+|\/+$/g, "")
+    .replace(/\/+/g, "/");
+}
+
+/**
+ * Checks if a string is a full URL with HTTP or HTTPS protocol.
+ *
+ * Validates whether a string starts with "http://" or "https://", indicating it's
+ * a full URL rather than a relative path. Useful for distinguishing between internal
+ * paths and external URLs.
+ *
+ * @param str - The string to check
+ * @returns `true` if the string starts with http:// or https://, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isFullUrl("https://example.com");  // Returns: true
+ * isFullUrl("/about");               // Returns: false
+ * isFullUrl("example.com");          // Returns: false
+ * ```
+ */
+export function isFullUrl(str: string): boolean {
+  return str.startsWith("http://") || str.startsWith("https://");
+}
+
+/**
+ * Converts text to a URL-friendly slug.
+ *
+ * Transforms text into a lowercase, hyphen-separated slug by:
+ * - Converting to lowercase
+ * - Removing special characters (keeping only word characters, spaces, and hyphens)
+ * - Replacing whitespace and underscores with hyphens
+ * - Removing leading and trailing hyphens
+ *
+ * Used for generating clean URLs from titles and names.
+ *
+ * @param text - The text to convert to a slug
+ * @returns The slugified string
+ *
+ * @example
+ * ```ts
+ * const slug = slugify("Hello World! This is a Test.");
+ * // Returns: "hello-world-this-is-a-test"
+ *
+ * const slug = slugify("  Multiple   Spaces  ");
+ * // Returns: "multiple-spaces"
+ * ```
+ */
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, "")
+    .replace(/[\s_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}

package/src/middleware/auth.ts

@@ -0,0 +1,59 @@
+/**
+ * Authentication Middleware
+ *
+ * Protects routes by requiring authentication
+ */
+
+import type { MiddlewareHandler } from "hono";
+import type { Bindings } from "../types.js";
+import type { AppVariables } from "../app.js";
+
+type Env = { Bindings: Bindings; Variables: AppVariables };
+
+/**
+ * Middleware that requires authentication.
+ * Redirects to signin page if not authenticated.
+ */
+export function requireAuth(redirectTo = "/signin"): MiddlewareHandler<Env> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      return c.redirect(redirectTo);
+    }
+
+    try {
+      const session = await c.var.auth.api.getSession({ headers: c.req.raw.headers });
+
+      if (!session?.user) {
+        return c.redirect(redirectTo);
+      }
+
+      await next();
+    } catch {
+      return c.redirect(redirectTo);
+    }
+  };
+}
+
+/**
+ * Middleware for API routes that requires authentication.
+ * Returns 401 if not authenticated.
+ */
+export function requireAuthApi(): MiddlewareHandler<Env> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      return c.json({ error: "Authentication not configured" }, 500);
+    }
+
+    try {
+      const session = await c.var.auth.api.getSession({ headers: c.req.raw.headers });
+
+      if (!session?.user) {
+        return c.json({ error: "Unauthorized" }, 401);
+      }
+
+      await next();
+    } catch {
+      return c.json({ error: "Unauthorized" }, 401);
+    }
+  };
+}

package/src/routes/api/posts.ts

@@ -0,0 +1,127 @@
+/**
+ * Posts API Routes
+ */
+
+import { Hono } from "hono";
+import type { Bindings, PostType, Visibility } from "../../types.js";
+import type { AppVariables } from "../../app.js";
+import * as sqid from "../../lib/sqid.js";
+import { CreatePostSchema, UpdatePostSchema } from "../../lib/schemas.js";
+import { requireAuthApi } from "../../middleware/auth.js";
+
+type Env = { Bindings: Bindings; Variables: AppVariables };
+
+export const postsApiRoutes = new Hono<Env>();
+
+// List posts
+postsApiRoutes.get("/", async (c) => {
+  const type = c.req.query("type") as PostType | undefined;
+  const visibility = c.req.query("visibility") as Visibility | undefined;
+  const cursor = c.req.query("cursor");
+  const limit = parseInt(c.req.query("limit") ?? "100", 10);
+
+  const posts = await c.var.services.posts.list({
+    type,
+    visibility: visibility ? [visibility] : ["featured", "quiet"],
+    cursor: cursor ? sqid.decode(cursor) ?? undefined : undefined,
+    limit,
+  });
+
+  return c.json({
+    posts: posts.map((p) => ({
+      ...p,
+      sqid: sqid.encode(p.id),
+    })),
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Array length check guarantees element exists
+    nextCursor: posts.length === limit ? sqid.encode(posts[posts.length - 1]!.id) : null,
+  });
+});
+
+// Get single post
+postsApiRoutes.get("/:id", async (c) => {
+  const id = sqid.decode(c.req.param("id"));
+  if (!id) return c.json({ error: "Invalid ID" }, 400);
+
+  const post = await c.var.services.posts.getById(id);
+  if (!post) return c.json({ error: "Not found" }, 404);
+
+  return c.json({ ...post, sqid: sqid.encode(post.id) });
+});
+
+// Create post (requires auth)
+postsApiRoutes.post("/", requireAuthApi(), async (c) => {
+
+  const rawBody = await c.req.json();
+
+  // Validate request body
+  const parseResult = CreatePostSchema.safeParse(rawBody);
+  if (!parseResult.success) {
+    return c.json(
+      { error: "Validation failed", details: parseResult.error.flatten() },
+      400
+    );
+  }
+
+  const body = parseResult.data;
+
+  const post = await c.var.services.posts.create({
+    type: body.type,
+    title: body.title,
+    content: body.content,
+    visibility: body.visibility,
+    sourceUrl: body.sourceUrl || undefined,
+    sourceName: body.sourceName,
+    path: body.path || undefined,
+    replyToId: body.replyToId ? sqid.decode(body.replyToId) ?? undefined : undefined,
+    publishedAt: body.publishedAt,
+  });
+
+  return c.json({ ...post, sqid: sqid.encode(post.id) }, 201);
+});
+
+// Update post (requires auth)
+postsApiRoutes.put("/:id", requireAuthApi(), async (c) => {
+
+  const id = sqid.decode(c.req.param("id"));
+  if (!id) return c.json({ error: "Invalid ID" }, 400);
+
+  const rawBody = await c.req.json();
+
+  // Validate request body
+  const parseResult = UpdatePostSchema.safeParse(rawBody);
+  if (!parseResult.success) {
+    return c.json(
+      { error: "Validation failed", details: parseResult.error.flatten() },
+      400
+    );
+  }
+
+  const body = parseResult.data;
+
+  const post = await c.var.services.posts.update(id, {
+    type: body.type,
+    title: body.title,
+    content: body.content,
+    visibility: body.visibility,
+    sourceUrl: body.sourceUrl,
+    sourceName: body.sourceName,
+    path: body.path,
+    publishedAt: body.publishedAt,
+  });
+
+  if (!post) return c.json({ error: "Not found" }, 404);
+
+  return c.json({ ...post, sqid: sqid.encode(post.id) });
+});
+
+// Delete post (requires auth)
+postsApiRoutes.delete("/:id", requireAuthApi(), async (c) => {
+
+  const id = sqid.decode(c.req.param("id"));
+  if (!id) return c.json({ error: "Invalid ID" }, 400);
+
+  const success = await c.var.services.posts.delete(id);
+  if (!success) return c.json({ error: "Not found" }, 404);
+
+  return c.json({ success: true });
+});

package/src/routes/api/search.ts

@@ -0,0 +1,53 @@
+/**
+ * Search API Routes
+ */
+
+import { Hono } from "hono";
+import type { Bindings } from "../../types.js";
+import type { AppVariables } from "../../app.js";
+import * as sqid from "../../lib/sqid.js";
+
+type Env = { Bindings: Bindings; Variables: AppVariables };
+
+export const searchApiRoutes = new Hono<Env>();
+
+// Search posts
+searchApiRoutes.get("/", async (c) => {
+  const query = c.req.query("q");
+
+  if (!query || query.trim().length === 0) {
+    return c.json({ error: "Query parameter 'q' is required" }, 400);
+  }
+
+  if (query.length > 200) {
+    return c.json({ error: "Query too long" }, 400);
+  }
+
+  const limitParam = c.req.query("limit");
+  const limit = limitParam ? Math.min(parseInt(limitParam, 10) || 20, 50) : 20;
+
+  try {
+    const results = await c.var.services.search.search(query, {
+      limit,
+      visibility: ["featured", "quiet"],
+    });
+
+    return c.json({
+      query,
+      results: results.map((r) => ({
+        id: sqid.encode(r.post.id),
+        type: r.post.type,
+        title: r.post.title,
+        path: r.post.path,
+        snippet: r.snippet,
+        publishedAt: r.post.publishedAt,
+        url: `/p/${sqid.encode(r.post.id)}`,
+      })),
+      count: results.length,
+    });
+  } catch (err) {
+    // eslint-disable-next-line no-console -- Error logging is intentional
+    console.error("Search error:", err);
+    return c.json({ error: "Search failed" }, 500);
+  }
+});