@hatk/hatk 0.0.1-alpha.21 → 0.0.1-alpha.23

package/dist/xrpc.js

@@ -6,12 +6,33 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+/**
+ * XRPC method handler system for serving AT Protocol endpoints.
+ *
+ * Place handler modules in the `xrpc/` directory, nested by NSID segments
+ * (e.g. `xrpc/app/bsky/feed/getAuthorFeed.ts` → `app.bsky.feed.getAuthorFeed`).
+ * Each module default-exports a `{ handler }` function that receives an
+ * {@link XrpcContext} with database access, query params, pagination, and
+ * viewer auth.
+ *
+ * @example
+ * ```ts
+ * // xrpc/xyz/statusphere/getStatuses.ts
+ * import { defineXrpc } from '../../hatk.generated.ts'
+ *
+ * export default defineXrpc('xyz.statusphere.getStatuses', async (ctx) => {
+ *   const rows = await ctx.db.query('SELECT * FROM statusphere_status LIMIT ?', [ctx.limit])
+ *   return { statuses: rows }
+ * })
+ * ```
+ */
 import { resolve, relative } from 'node:path';
 import { readdirSync, statSync } from 'node:fs';
 import { log } from "./logger.js";
-import { querySQL, runSQL, packCursor, unpackCursor, isTakendownDid, filterTakendownDids, searchRecords, findUriByFields, lookupByFieldBatch, countByFieldBatch, queryLabelsForUris, } from "./db.js";
+import { querySQL, runSQL, packCursor, unpackCursor, isTakendownDid, filterTakendownDids, searchRecords, findUriByFields, lookupByFieldBatch, countByFieldBatch, queryLabelsForUris, } from "./database/db.js";
 import { resolveRecords } from "./hydrate.js";
-import { getLexicon } from "./schema.js";
+import { getLexicon } from "./database/schema.js";
+/** Thrown from XRPC handlers to return a 400 response with an error message. */
 export class InvalidRequestError extends Error {
     status = 400;
     errorName;
@@ -20,6 +41,7 @@ export class InvalidRequestError extends Error {
         this.errorName = errorName;
     }
 }
+/** Thrown from XRPC handlers to return a 404 response. */
 export class NotFoundError extends InvalidRequestError {
     status = 404;
     constructor(message = 'Not found') {
@@ -27,9 +49,14 @@ export class NotFoundError extends InvalidRequestError {
     }
 }
 let _relayUrl = '';
+/** Set the relay URL used for blob URL generation. Called once during boot. */
 export function configureRelay(relay) {
     _relayUrl = relay;
 }
+/**
+ * Generate a CDN URL for a blob ref. Uses the PDS directly in local dev,
+ * or the Bluesky CDN (`cdn.bsky.app`) in production.
+ */
 export function blobUrl(did, ref, preset = 'avatar') {
     if (!ref)
         return undefined;
@@ -42,6 +69,7 @@ export function blobUrl(did, ref, preset = 'avatar') {
     return `https://cdn.bsky.app/img/${preset}/plain/${did}/${p.ref.$link}@jpeg`;
 }
 const handlers = new Map();
+/** Recursively collect .ts/.js files in a directory, skipping files prefixed with `_`. */
 function walkDir(dir) {
     const results = [];
     try {
@@ -58,6 +86,11 @@ function walkDir(dir) {
     catch { }
     return results.sort();
 }
+/**
+ * Discover and load XRPC handler modules from the `xrpc/` directory.
+ * Directory nesting maps to NSID segments. Parameters are validated and
+ * coerced against the matching lexicon definition.
+ */
 export async function initXrpc(xrpcDir) {
     const files = walkDir(xrpcDir);
     if (files.length === 0)
@@ -128,12 +161,14 @@ export async function initXrpc(xrpcDir) {
         log(`[xrpc] discovered: ${name}`);
     }
 }
+/** Execute a registered XRPC handler by name. Returns null if no handler matches. */
 export async function executeXrpc(name, params, cursor, limit, viewer, input) {
     const handler = handlers.get(name);
     if (!handler)
         return null;
     return handler.execute(params, cursor, limit, viewer || null, input);
 }
+/** Return all registered XRPC method names. */
 export function listXrpc() {
     return Array.from(handlers.keys());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatk/hatk",
-  "version": "0.0.1-alpha.21",
+  "version": "0.0.1-alpha.23",
   "license": "MIT",
   "bin": {
     "hatk": "dist/cli.js"
@@ -35,12 +35,14 @@
     "@duckdb/node-api": "^1.4.4-r.1",
     "@hatk/oauth-client": "*",
     "@resvg/resvg-js": "^2.6.2",
+    "better-sqlite3": "^12.6.2",
     "satori": "^0.19.2",
     "vitest": "^4",
     "yaml": "^2.7.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.2",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/react": "^19.2.14",
     "vite": "^6"
   }