@parsrun/server 0.1.0

package/dist/rls.d.ts

@@ -0,0 +1,114 @@
+import { DatabaseAdapter, Middleware } from './context.js';
+import 'hono';
+import '@parsrun/core';
+
+/**
+ * @parsrun/server - Row Level Security (RLS) Manager
+ * PostgreSQL RLS integration for multi-tenant isolation
+ */
+
+/**
+ * RLS configuration
+ */
+interface RLSConfig {
+    /** Tenant ID column name (default: tenant_id) */
+    tenantIdColumn?: string;
+    /** PostgreSQL session variable name (default: app.current_tenant_id) */
+    sessionVariable?: string;
+    /** Enable RLS by default */
+    enabled?: boolean;
+}
+/**
+ * RLS Manager for tenant isolation
+ *
+ * @example
+ * ```typescript
+ * const rls = new RLSManager(db);
+ *
+ * // Set tenant context
+ * await rls.setTenantId("tenant-123");
+ *
+ * // All queries now filtered by tenant
+ * const items = await db.select().from(items);
+ *
+ * // Clear when done
+ * await rls.clearTenantId();
+ *
+ * // Or use withTenant helper
+ * await rls.withTenant("tenant-123", async () => {
+ *   return await db.select().from(items);
+ * });
+ * ```
+ */
+declare class RLSManager {
+    private db;
+    private config;
+    constructor(db: DatabaseAdapter, config?: RLSConfig);
+    /**
+     * Set current tenant ID in database session
+     * This enables RLS policies to filter by tenant
+     */
+    setTenantId(tenantId: string): Promise<void>;
+    /**
+     * Clear current tenant ID from database session
+     */
+    clearTenantId(): Promise<void>;
+    /**
+     * Execute a function with tenant context
+     * Automatically sets and clears tenant ID
+     */
+    withTenant<T>(tenantId: string, operation: () => Promise<T>): Promise<T>;
+    /**
+     * Check if RLS is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Required<RLSConfig>;
+}
+/**
+ * RLS Error class
+ */
+declare class RLSError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+/**
+ * Create RLS manager
+ */
+declare function createRLSManager(db: DatabaseAdapter, config?: RLSConfig): RLSManager;
+/**
+ * RLS Middleware
+ * Automatically sets tenant context for authenticated requests
+ *
+ * @example
+ * ```typescript
+ * app.use('*', rlsMiddleware());
+ * ```
+ */
+declare function rlsMiddleware(config?: RLSConfig): Middleware;
+/**
+ * Create SQL for enabling RLS on a table
+ *
+ * @example
+ * ```sql
+ * -- Generated SQL:
+ * ALTER TABLE items ENABLE ROW LEVEL SECURITY;
+ * CREATE POLICY items_tenant_isolation ON items
+ *   USING (tenant_id = current_setting('app.current_tenant_id')::uuid);
+ * ```
+ */
+declare function generateRLSPolicy(tableName: string, options?: {
+    tenantIdColumn?: string;
+    sessionVariable?: string;
+    policyName?: string;
+    castType?: string;
+}): string;
+/**
+ * Create SQL for disabling RLS on a table
+ */
+declare function generateDisableRLS(tableName: string): string;
+
+export { type RLSConfig, RLSError, RLSManager, createRLSManager, generateDisableRLS, generateRLSPolicy, rlsMiddleware };

package/dist/rls.js

@@ -0,0 +1,126 @@
+// src/rls.ts
+var DEFAULT_RLS_CONFIG = {
+  tenantIdColumn: "tenant_id",
+  sessionVariable: "app.current_tenant_id",
+  enabled: true
+};
+var RLSManager = class {
+  constructor(db, config = {}) {
+    this.db = db;
+    this.config = { ...DEFAULT_RLS_CONFIG, ...config };
+  }
+  config;
+  /**
+   * Set current tenant ID in database session
+   * This enables RLS policies to filter by tenant
+   */
+  async setTenantId(tenantId) {
+    if (!this.config.enabled) return;
+    try {
+      const escapedTenantId = tenantId.replace(/'/g, "''");
+      await this.db.execute(`SET ${this.config.sessionVariable} = '${escapedTenantId}'`);
+    } catch (error) {
+      console.error("Failed to set tenant ID for RLS:", error);
+      throw new RLSError("Failed to set tenant context", "RLS_SET_FAILED", error);
+    }
+  }
+  /**
+   * Clear current tenant ID from database session
+   */
+  async clearTenantId() {
+    if (!this.config.enabled) return;
+    try {
+      await this.db.execute(`RESET ${this.config.sessionVariable}`);
+    } catch (error) {
+      console.error("Failed to clear tenant ID for RLS:", error);
+      throw new RLSError("Failed to clear tenant context", "RLS_CLEAR_FAILED", error);
+    }
+  }
+  /**
+   * Execute a function with tenant context
+   * Automatically sets and clears tenant ID
+   */
+  async withTenant(tenantId, operation) {
+    await this.setTenantId(tenantId);
+    try {
+      return await operation();
+    } finally {
+      await this.clearTenantId();
+    }
+  }
+  /**
+   * Check if RLS is enabled
+   */
+  isEnabled() {
+    return this.config.enabled;
+  }
+  /**
+   * Get current configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+};
+var RLSError = class extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+    this.name = "RLSError";
+  }
+};
+function createRLSManager(db, config) {
+  return new RLSManager(db, config);
+}
+function rlsMiddleware(config) {
+  return async (c, next) => {
+    const user = c.get("user");
+    const db = c.get("db");
+    if (!user?.tenantId || !db) {
+      return next();
+    }
+    const rls = new RLSManager(db, config);
+    try {
+      await rls.setTenantId(user.tenantId);
+      await next();
+    } finally {
+      await rls.clearTenantId();
+    }
+  };
+}
+function generateRLSPolicy(tableName, options = {}) {
+  const {
+    tenantIdColumn = "tenant_id",
+    sessionVariable = "app.current_tenant_id",
+    policyName = `${tableName}_tenant_isolation`,
+    castType = "uuid"
+  } = options;
+  return `
+-- Enable RLS on table
+ALTER TABLE ${tableName} ENABLE ROW LEVEL SECURITY;
+
+-- Force RLS for table owner too
+ALTER TABLE ${tableName} FORCE ROW LEVEL SECURITY;
+
+-- Create tenant isolation policy
+DROP POLICY IF EXISTS ${policyName} ON ${tableName};
+CREATE POLICY ${policyName} ON ${tableName}
+  FOR ALL
+  USING (${tenantIdColumn} = current_setting('${sessionVariable}', true)::${castType});
+`.trim();
+}
+function generateDisableRLS(tableName) {
+  return `
+ALTER TABLE ${tableName} DISABLE ROW LEVEL SECURITY;
+ALTER TABLE ${tableName} NO FORCE ROW LEVEL SECURITY;
+`.trim();
+}
+export {
+  RLSError,
+  RLSManager,
+  createRLSManager,
+  generateDisableRLS,
+  generateRLSPolicy,
+  rlsMiddleware
+};
+//# sourceMappingURL=rls.js.map

package/dist/rls.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/rls.ts"],"sourcesContent":["/**\n * @parsrun/server - Row Level Security (RLS) Manager\n * PostgreSQL RLS integration for multi-tenant isolation\n */\n\nimport type { DatabaseAdapter, HonoContext, HonoNext, Middleware } from \"./context.js\";\n\n/**\n * RLS configuration\n */\nexport interface RLSConfig {\n  /** Tenant ID column name (default: tenant_id) */\n  tenantIdColumn?: string;\n  /** PostgreSQL session variable name (default: app.current_tenant_id) */\n  sessionVariable?: string;\n  /** Enable RLS by default */\n  enabled?: boolean;\n}\n\n/**\n * Default RLS configuration\n */\nconst DEFAULT_RLS_CONFIG: Required<RLSConfig> = {\n  tenantIdColumn: \"tenant_id\",\n  sessionVariable: \"app.current_tenant_id\",\n  enabled: true,\n};\n\n/**\n * RLS Manager for tenant isolation\n *\n * @example\n * ```typescript\n * const rls = new RLSManager(db);\n *\n * // Set tenant context\n * await rls.setTenantId(\"tenant-123\");\n *\n * // All queries now filtered by tenant\n * const items = await db.select().from(items);\n *\n * // Clear when done\n * await rls.clearTenantId();\n *\n * // Or use withTenant helper\n * await rls.withTenant(\"tenant-123\", async () => {\n *   return await db.select().from(items);\n * });\n * ```\n */\nexport class RLSManager {\n  private config: Required<RLSConfig>;\n\n  constructor(\n    private db: DatabaseAdapter,\n    config: RLSConfig = {}\n  ) {\n    this.config = { ...DEFAULT_RLS_CONFIG, ...config };\n  }\n\n  /**\n   * Set current tenant ID in database session\n   * This enables RLS policies to filter by tenant\n   */\n  async setTenantId(tenantId: string): Promise<void> {\n    if (!this.config.enabled) return;\n\n    try {\n      // Use parameterized query to prevent SQL injection\n      // PostgreSQL SET command with escaped string\n      const escapedTenantId = tenantId.replace(/'/g, \"''\");\n      await this.db.execute(`SET ${this.config.sessionVariable} = '${escapedTenantId}'`);\n    } catch (error) {\n      console.error(\"Failed to set tenant ID for RLS:\", error);\n      throw new RLSError(\"Failed to set tenant context\", \"RLS_SET_FAILED\", error);\n    }\n  }\n\n  /**\n   * Clear current tenant ID from database session\n   */\n  async clearTenantId(): Promise<void> {\n    if (!this.config.enabled) return;\n\n    try {\n      await this.db.execute(`RESET ${this.config.sessionVariable}`);\n    } catch (error) {\n      console.error(\"Failed to clear tenant ID for RLS:\", error);\n      throw new RLSError(\"Failed to clear tenant context\", \"RLS_CLEAR_FAILED\", error);\n    }\n  }\n\n  /**\n   * Execute a function with tenant context\n   * Automatically sets and clears tenant ID\n   */\n  async withTenant<T>(tenantId: string, operation: () => Promise<T>): Promise<T> {\n    await this.setTenantId(tenantId);\n    try {\n      return await operation();\n    } finally {\n      await this.clearTenantId();\n    }\n  }\n\n  /**\n   * Check if RLS is enabled\n   */\n  isEnabled(): boolean {\n    return this.config.enabled;\n  }\n\n  /**\n   * Get current configuration\n   */\n  getConfig(): Required<RLSConfig> {\n    return { ...this.config };\n  }\n}\n\n/**\n * RLS Error class\n */\nexport class RLSError extends Error {\n  constructor(\n    message: string,\n    public readonly code: string,\n    public readonly cause?: unknown\n  ) {\n    super(message);\n    this.name = \"RLSError\";\n  }\n}\n\n/**\n * Create RLS manager\n */\nexport function createRLSManager(db: DatabaseAdapter, config?: RLSConfig): RLSManager {\n  return new RLSManager(db, config);\n}\n\n/**\n * RLS Middleware\n * Automatically sets tenant context for authenticated requests\n *\n * @example\n * ```typescript\n * app.use('*', rlsMiddleware());\n * ```\n */\nexport function rlsMiddleware(config?: RLSConfig): Middleware {\n  return async (c: HonoContext, next: HonoNext): Promise<Response | void> => {\n    const user = c.get(\"user\");\n    const db = c.get(\"db\");\n\n    // Skip if no user or no tenant\n    if (!user?.tenantId || !db) {\n      return next();\n    }\n\n    const rls = new RLSManager(db, config);\n\n    try {\n      await rls.setTenantId(user.tenantId);\n      await next();\n    } finally {\n      await rls.clearTenantId();\n    }\n  };\n}\n\n/**\n * Create SQL for enabling RLS on a table\n *\n * @example\n * ```sql\n * -- Generated SQL:\n * ALTER TABLE items ENABLE ROW LEVEL SECURITY;\n * CREATE POLICY items_tenant_isolation ON items\n *   USING (tenant_id = current_setting('app.current_tenant_id')::uuid);\n * ```\n */\nexport function generateRLSPolicy(\n  tableName: string,\n  options: {\n    tenantIdColumn?: string;\n    sessionVariable?: string;\n    policyName?: string;\n    castType?: string;\n  } = {}\n): string {\n  const {\n    tenantIdColumn = \"tenant_id\",\n    sessionVariable = \"app.current_tenant_id\",\n    policyName = `${tableName}_tenant_isolation`,\n    castType = \"uuid\",\n  } = options;\n\n  return `\n-- Enable RLS on table\nALTER TABLE ${tableName} ENABLE ROW LEVEL SECURITY;\n\n-- Force RLS for table owner too\nALTER TABLE ${tableName} FORCE ROW LEVEL SECURITY;\n\n-- Create tenant isolation policy\nDROP POLICY IF EXISTS ${policyName} ON ${tableName};\nCREATE POLICY ${policyName} ON ${tableName}\n  FOR ALL\n  USING (${tenantIdColumn} = current_setting('${sessionVariable}', true)::${castType});\n`.trim();\n}\n\n/**\n * Create SQL for disabling RLS on a table\n */\nexport function generateDisableRLS(tableName: string): string {\n  return `\nALTER TABLE ${tableName} DISABLE ROW LEVEL SECURITY;\nALTER TABLE ${tableName} NO FORCE ROW LEVEL SECURITY;\n`.trim();\n}\n"],"mappings":";AAsBA,IAAM,qBAA0C;AAAA,EAC9C,gBAAgB;AAAA,EAChB,iBAAiB;AAAA,EACjB,SAAS;AACX;AAwBO,IAAM,aAAN,MAAiB;AAAA,EAGtB,YACU,IACR,SAAoB,CAAC,GACrB;AAFQ;AAGR,SAAK,SAAS,EAAE,GAAG,oBAAoB,GAAG,OAAO;AAAA,EACnD;AAAA,EAPQ;AAAA;AAAA;AAAA;AAAA;AAAA,EAaR,MAAM,YAAY,UAAiC;AACjD,QAAI,CAAC,KAAK,OAAO,QAAS;AAE1B,QAAI;AAGF,YAAM,kBAAkB,SAAS,QAAQ,MAAM,IAAI;AACnD,YAAM,KAAK,GAAG,QAAQ,OAAO,KAAK,OAAO,eAAe,OAAO,eAAe,GAAG;AAAA,IACnF,SAAS,OAAO;AACd,cAAQ,MAAM,oCAAoC,KAAK;AACvD,YAAM,IAAI,SAAS,gCAAgC,kBAAkB,KAAK;AAAA,IAC5E;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,gBAA+B;AACnC,QAAI,CAAC,KAAK,OAAO,QAAS;AAE1B,QAAI;AACF,YAAM,KAAK,GAAG,QAAQ,SAAS,KAAK,OAAO,eAAe,EAAE;AAAA,IAC9D,SAAS,OAAO;AACd,cAAQ,MAAM,sCAAsC,KAAK;AACzD,YAAM,IAAI,SAAS,kCAAkC,oBAAoB,KAAK;AAAA,IAChF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,WAAc,UAAkB,WAAyC;AAC7E,UAAM,KAAK,YAAY,QAAQ;AAC/B,QAAI;AACF,aAAO,MAAM,UAAU;AAAA,IACzB,UAAE;AACA,YAAM,KAAK,cAAc;AAAA,IAC3B;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,YAAqB;AACnB,WAAO,KAAK,OAAO;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA,EAKA,YAAiC;AAC/B,WAAO,EAAE,GAAG,KAAK,OAAO;AAAA,EAC1B;AACF;AAKO,IAAM,WAAN,cAAuB,MAAM;AAAA,EAClC,YACE,SACgB,MACA,OAChB;AACA,UAAM,OAAO;AAHG;AACA;AAGhB,SAAK,OAAO;AAAA,EACd;AACF;AAKO,SAAS,iBAAiB,IAAqB,QAAgC;AACpF,SAAO,IAAI,WAAW,IAAI,MAAM;AAClC;AAWO,SAAS,cAAc,QAAgC;AAC5D,SAAO,OAAO,GAAgB,SAA6C;AACzE,UAAM,OAAO,EAAE,IAAI,MAAM;AACzB,UAAM,KAAK,EAAE,IAAI,IAAI;AAGrB,QAAI,CAAC,MAAM,YAAY,CAAC,IAAI;AAC1B,aAAO,KAAK;AAAA,IACd;AAEA,UAAM,MAAM,IAAI,WAAW,IAAI,MAAM;AAErC,QAAI;AACF,YAAM,IAAI,YAAY,KAAK,QAAQ;AACnC,YAAM,KAAK;AAAA,IACb,UAAE;AACA,YAAM,IAAI,cAAc;AAAA,IAC1B;AAAA,EACF;AACF;AAaO,SAAS,kBACd,WACA,UAKI,CAAC,GACG;AACR,QAAM;AAAA,IACJ,iBAAiB;AAAA,IACjB,kBAAkB;AAAA,IAClB,aAAa,GAAG,SAAS;AAAA,IACzB,WAAW;AAAA,EACb,IAAI;AAEJ,SAAO;AAAA;AAAA,cAEK,SAAS;AAAA;AAAA;AAAA,cAGT,SAAS;AAAA;AAAA;AAAA,wBAGC,UAAU,OAAO,SAAS;AAAA,gBAClC,UAAU,OAAO,SAAS;AAAA;AAAA,WAE/B,cAAc,uBAAuB,eAAe,aAAa,QAAQ;AAAA,EAClF,KAAK;AACP;AAKO,SAAS,mBAAmB,WAA2B;AAC5D,SAAO;AAAA,cACK,SAAS;AAAA,cACT,SAAS;AAAA,EACrB,KAAK;AACP;","names":[]}

package/dist/utils/index.d.ts

@@ -0,0 +1,262 @@
+import { HonoContext, ApiResponse } from '../context.js';
+import 'hono';
+import '@parsrun/core';
+
+/**
+ * @parsrun/server - Pagination Utilities
+ * Helpers for paginated API responses
+ */
+
+/**
+ * Pagination parameters
+ */
+interface PaginationParams {
+    page: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Pagination metadata
+ */
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+/**
+ * Paginated response
+ */
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: PaginationMeta;
+}
+/**
+ * Pagination options
+ */
+interface PaginationOptions {
+    /** Default page size */
+    defaultLimit?: number;
+    /** Maximum page size */
+    maxLimit?: number;
+    /** Page query parameter name */
+    pageParam?: string;
+    /** Limit query parameter name */
+    limitParam?: string;
+}
+/**
+ * Parse pagination from request query
+ *
+ * @example
+ * ```typescript
+ * app.get('/users', async (c) => {
+ *   const { page, limit, offset } = parsePagination(c);
+ *
+ *   const users = await db.query.users.findMany({
+ *     limit,
+ *     offset,
+ *   });
+ *
+ *   const total = await db.query.users.count();
+ *
+ *   return c.json(paginate(users, { page, limit, total }));
+ * });
+ * ```
+ */
+declare function parsePagination(c: HonoContext, options?: PaginationOptions): PaginationParams;
+/**
+ * Create pagination metadata
+ */
+declare function createPaginationMeta(params: {
+    page: number;
+    limit: number;
+    total: number;
+}): PaginationMeta;
+/**
+ * Create paginated response
+ *
+ * @example
+ * ```typescript
+ * const users = await getUsers({ limit, offset });
+ * const total = await countUsers();
+ *
+ * return c.json(paginate(users, { page, limit, total }));
+ * ```
+ */
+declare function paginate<T>(data: T[], params: {
+    page: number;
+    limit: number;
+    total: number;
+}): PaginatedResponse<T>;
+/**
+ * Cursor-based pagination params
+ */
+interface CursorPaginationParams {
+    cursor?: string | undefined;
+    limit: number;
+    direction: "forward" | "backward";
+}
+/**
+ * Cursor pagination metadata
+ */
+interface CursorPaginationMeta {
+    cursor?: string | undefined;
+    nextCursor?: string | undefined;
+    prevCursor?: string | undefined;
+    hasMore: boolean;
+    limit: number;
+}
+/**
+ * Cursor paginated response
+ */
+interface CursorPaginatedResponse<T> {
+    data: T[];
+    pagination: CursorPaginationMeta;
+}
+/**
+ * Parse cursor pagination from request
+ *
+ * @example
+ * ```typescript
+ * app.get('/feed', async (c) => {
+ *   const { cursor, limit, direction } = parseCursorPagination(c);
+ *
+ *   const items = await db.query.posts.findMany({
+ *     where: cursor ? { id: { gt: cursor } } : undefined,
+ *     limit: limit + 1, // Fetch one extra to check hasMore
+ *     orderBy: { createdAt: 'desc' },
+ *   });
+ *
+ *   return c.json(cursorPaginate(items, { cursor, limit }));
+ * });
+ * ```
+ */
+declare function parseCursorPagination(c: HonoContext, options?: PaginationOptions): CursorPaginationParams;
+/**
+ * Create cursor paginated response
+ *
+ * @example
+ * ```typescript
+ * // Fetch limit + 1 items
+ * const items = await fetchItems(limit + 1);
+ * return c.json(cursorPaginate(items, { cursor, limit }));
+ * ```
+ */
+declare function cursorPaginate<T extends {
+    id: string;
+}>(data: T[], params: {
+    cursor?: string;
+    limit: number;
+}): CursorPaginatedResponse<T>;
+/**
+ * Add pagination headers to response
+ */
+declare function setPaginationHeaders(c: HonoContext, meta: PaginationMeta): void;
+
+/**
+ * @parsrun/server - Response Utilities
+ * Helpers for API responses
+ */
+
+/**
+ * Send JSON success response
+ *
+ * @example
+ * ```typescript
+ * app.get('/users/:id', async (c) => {
+ *   const user = await getUser(c.req.param('id'));
+ *   return json(c, user);
+ * });
+ * ```
+ */
+declare function json<T>(c: HonoContext, data: T, status?: number): Response;
+/**
+ * Send JSON success response with metadata
+ *
+ * @example
+ * ```typescript
+ * app.get('/users', async (c) => {
+ *   const { users, total } = await getUsers();
+ *   return jsonWithMeta(c, users, { total, page: 1, limit: 20 });
+ * });
+ * ```
+ */
+declare function jsonWithMeta<T>(c: HonoContext, data: T, meta: ApiResponse["meta"], status?: number): Response;
+/**
+ * Send JSON error response
+ *
+ * @example
+ * ```typescript
+ * app.get('/users/:id', async (c) => {
+ *   const user = await getUser(c.req.param('id'));
+ *   if (!user) {
+ *     return jsonError(c, 'USER_NOT_FOUND', 'User not found', 404);
+ *   }
+ *   return json(c, user);
+ * });
+ * ```
+ */
+declare function jsonError(c: HonoContext, code: string, message: string, status?: number, details?: Record<string, unknown>): Response;
+/**
+ * Send created response (201)
+ */
+declare function created<T>(c: HonoContext, data: T, location?: string): Response;
+/**
+ * Send no content response (204)
+ */
+declare function noContent(_c: HonoContext): Response;
+/**
+ * Send accepted response (202) - for async operations
+ */
+declare function accepted<T>(c: HonoContext, data?: T): Response;
+/**
+ * Redirect response
+ */
+declare function redirect(c: HonoContext, url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+/**
+ * Stream response helper
+ *
+ * @example
+ * ```typescript
+ * app.get('/stream', (c) => {
+ *   return stream(c, async (write) => {
+ *     for (let i = 0; i < 10; i++) {
+ *       await write(`data: ${i}\n\n`);
+ *       await new Promise(r => setTimeout(r, 1000));
+ *     }
+ *   });
+ * });
+ * ```
+ */
+declare function stream(_c: HonoContext, callback: (write: (chunk: string) => Promise<void>) => Promise<void>, options?: {
+    contentType?: string;
+    headers?: Record<string, string>;
+}): Response;
+/**
+ * Server-Sent Events helper
+ *
+ * @example
+ * ```typescript
+ * app.get('/events', (c) => {
+ *   return sse(c, async (send) => {
+ *     for await (const event of eventStream) {
+ *       await send({ event: 'update', data: event });
+ *     }
+ *   });
+ * });
+ * ```
+ */
+declare function sse(c: HonoContext, callback: (send: (event: {
+    event?: string;
+    data: unknown;
+    id?: string;
+    retry?: number;
+}) => Promise<void>) => Promise<void>): Response;
+/**
+ * File download response
+ */
+declare function download(c: HonoContext, data: Uint8Array | ArrayBuffer | string, filename: string, contentType?: string): Response;
+
+export { type CursorPaginatedResponse, type CursorPaginationMeta, type CursorPaginationParams, type PaginatedResponse, type PaginationMeta, type PaginationOptions, type PaginationParams, accepted, createPaginationMeta, created, cursorPaginate, download, json, jsonError, jsonWithMeta, noContent, paginate, parseCursorPagination, parsePagination, redirect, setPaginationHeaders, sse, stream };

package/dist/utils/index.js

@@ -0,0 +1,193 @@
+// src/utils/pagination.ts
+var defaultOptions = {
+  defaultLimit: 20,
+  maxLimit: 100,
+  pageParam: "page",
+  limitParam: "limit"
+};
+function parsePagination(c, options = {}) {
+  const opts = { ...defaultOptions, ...options };
+  const pageStr = c.req.query(opts.pageParam);
+  const limitStr = c.req.query(opts.limitParam);
+  let page = pageStr ? parseInt(pageStr, 10) : 1;
+  let limit = limitStr ? parseInt(limitStr, 10) : opts.defaultLimit;
+  if (isNaN(page) || page < 1) page = 1;
+  if (isNaN(limit) || limit < 1) limit = opts.defaultLimit;
+  if (limit > opts.maxLimit) limit = opts.maxLimit;
+  const offset = (page - 1) * limit;
+  return { page, limit, offset };
+}
+function createPaginationMeta(params) {
+  const { page, limit, total } = params;
+  const totalPages = Math.ceil(total / limit);
+  return {
+    page,
+    limit,
+    total,
+    totalPages,
+    hasNext: page < totalPages,
+    hasPrev: page > 1
+  };
+}
+function paginate(data, params) {
+  return {
+    data,
+    pagination: createPaginationMeta(params)
+  };
+}
+function parseCursorPagination(c, options = {}) {
+  const opts = { ...defaultOptions, ...options };
+  const cursor = c.req.query("cursor") ?? void 0;
+  const limitStr = c.req.query(opts.limitParam);
+  const direction = c.req.query("direction") === "backward" ? "backward" : "forward";
+  let limit = limitStr ? parseInt(limitStr, 10) : opts.defaultLimit;
+  if (isNaN(limit) || limit < 1) limit = opts.defaultLimit;
+  if (limit > opts.maxLimit) limit = opts.maxLimit;
+  return { cursor, limit, direction };
+}
+function cursorPaginate(data, params) {
+  const { cursor, limit } = params;
+  const hasMore = data.length > limit;
+  const items = hasMore ? data.slice(0, limit) : data;
+  const lastItem = items[items.length - 1];
+  const firstItem = items[0];
+  return {
+    data: items,
+    pagination: {
+      cursor,
+      nextCursor: hasMore && lastItem ? lastItem.id : void 0,
+      prevCursor: cursor && firstItem ? firstItem.id : void 0,
+      hasMore,
+      limit
+    }
+  };
+}
+function setPaginationHeaders(c, meta) {
+  c.header("X-Total-Count", String(meta.total));
+  c.header("X-Total-Pages", String(meta.totalPages));
+  c.header("X-Page", String(meta.page));
+  c.header("X-Per-Page", String(meta.limit));
+  c.header("X-Has-Next", String(meta.hasNext));
+  c.header("X-Has-Prev", String(meta.hasPrev));
+}
+
+// src/context.ts
+function success(data, meta) {
+  return {
+    success: true,
+    data,
+    meta: meta ?? void 0
+  };
+}
+function error(code, message, details) {
+  return {
+    success: false,
+    error: { code, message, details: details ?? void 0 }
+  };
+}
+
+// src/utils/response.ts
+function json(c, data, status = 200) {
+  return c.json(success(data), status);
+}
+function jsonWithMeta(c, data, meta, status = 200) {
+  return c.json(success(data, meta), status);
+}
+function jsonError(c, code, message, status = 400, details) {
+  return c.json(error(code, message, details), status);
+}
+function created(c, data, location) {
+  if (location) {
+    c.header("Location", location);
+  }
+  return c.json(success(data), 201);
+}
+function noContent(_c) {
+  return new Response(null, { status: 204 });
+}
+function accepted(c, data) {
+  if (data) {
+    return c.json(success(data), 202);
+  }
+  return new Response(null, { status: 202 });
+}
+function redirect(c, url, status = 302) {
+  return c.redirect(url, status);
+}
+function stream(_c, callback, options = {}) {
+  const encoder = new TextEncoder();
+  const readableStream = new ReadableStream({
+    async start(controller) {
+      const write = async (chunk) => {
+        controller.enqueue(encoder.encode(chunk));
+      };
+      try {
+        await callback(write);
+      } finally {
+        controller.close();
+      }
+    }
+  });
+  return new Response(readableStream, {
+    headers: {
+      "Content-Type": options.contentType ?? "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      ...options.headers
+    }
+  });
+}
+function sse(c, callback) {
+  return stream(c, async (write) => {
+    const send = async (event) => {
+      let message = "";
+      if (event.id) {
+        message += `id: ${event.id}
+`;
+      }
+      if (event.event) {
+        message += `event: ${event.event}
+`;
+      }
+      if (event.retry) {
+        message += `retry: ${event.retry}
+`;
+      }
+      const data = typeof event.data === "string" ? event.data : JSON.stringify(event.data);
+      message += `data: ${data}
+
+`;
+      await write(message);
+    };
+    await callback(send);
+  });
+}
+function download(c, data, filename, contentType = "application/octet-stream") {
+  c.header("Content-Disposition", `attachment; filename="${filename}"`);
+  c.header("Content-Type", contentType);
+  if (typeof data === "string") {
+    return c.body(data);
+  }
+  return new Response(data, {
+    headers: c.res.headers
+  });
+}
+export {
+  accepted,
+  createPaginationMeta,
+  created,
+  cursorPaginate,
+  download,
+  json,
+  jsonError,
+  jsonWithMeta,
+  noContent,
+  paginate,
+  parseCursorPagination,
+  parsePagination,
+  redirect,
+  setPaginationHeaders,
+  sse,
+  stream
+};
+//# sourceMappingURL=index.js.map