@gravito/echo 3.0.0 → 3.1.0

package/dist/photon/src/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @gravito/photon - High-performance web engine for the Gravito Galaxy Architecture.
+ *
+ * Photon serves as the foundational HTTP layer for Gravito, providing an ultra-fast,
+ * type-safe routing system based on Hono. It is designed to be the "light" that
+ * connects Satellites (domain plugins) and Orbits (infrastructure) within the ecosystem.
+ *
+ * Key features:
+ * - Zero-overhead routing and middleware.
+ * - Full TypeScript inference for request parameters and body.
+ * - Built-in support for HTMX and binary (CBOR) protocols.
+ *
+ * @example
+ * ```typescript
+ * import { Photon } from '@gravito/photon'
+ *
+ * const app = new Photon()
+ *
+ * app.get('/welcome', (c) => c.text('Welcome to the Galaxy!'))
+ *
+ * export default app
+ * ```
+ * @packageDocumentation
+ */
+export * from 'hono';
+/**
+ * The primary application class for Photon.
+ *
+ * An alias for `Hono`, providing the core routing and middleware capabilities.
+ * Use this to define your API structure and mount domain-specific Satellites.
+ *
+ * @remarks
+ * Photon extends Hono's capabilities with Gravito-specific optimizations.
+ * It serves as the entry point for defining routes, applying middleware,
+ * and handling the request-response lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const app = new Photon()
+ *
+ * // Basic routing
+ * app.get('/api/health', (c) => c.json({ status: 'ok' }))
+ *
+ * // Middleware integration
+ * app.use('/api/*', myMiddleware)
+ *
+ * // Mounting sub-routers
+ * app.route('/v1', v1Router)
+ * ```
+ * @public
+ */
+export { Hono as Photon } from 'hono';
+/**
+ * Binary-related middleware for Photon.
+ *
+ * Provides utilities for handling binary data formats like CBOR,
+ * optimizing payload size and serialization speed for high-performance APIs.
+ *
+ * @public
+ */
+export * from './middleware/binary';
+/**
+ * HTMX-related middleware for Photon.
+ *
+ * Enhances Photon with first-class support for HTMX, including
+ * automatic request detection and simplified header access for hypermedia-driven UIs.
+ *
+ * @public
+ */
+export * from './middleware/htmx';
+/**
+ * Rate limiting middleware for Photon.
+ *
+ * Provides built-in rate limiting with token bucket and sliding window strategies.
+ * Supports both memory-based and custom storage backends.
+ *
+ * @public
+ */
+export * from './middleware/ratelimit';
+/**
+ * OpenAPI utilities
+ * @public
+ */
+export * from './openapi';

package/dist/photon/src/middleware/binary.d.ts

@@ -0,0 +1,31 @@
+import type { MiddlewareHandler } from 'hono';
+/**
+ * Binary Middleware for Photon.
+ *
+ * Automatically detects 'Accept: application/cbor' and encodes
+ * JSON responses using the CBOR binary format for high-performance communication.
+ *
+ * @remarks
+ * This middleware is essential for high-frequency API calls where payload size
+ * and serialization speed are critical. It leverages the `cborg` library for
+ * efficient binary encoding.
+ *
+ * @returns A Hono middleware handler that intercepts JSON responses.
+ *
+ * @example
+ * ```typescript
+ * import { Photon } from '@gravito/photon'
+ * import { binaryMiddleware } from '@gravito/photon/middleware/binary'
+ *
+ * const app = new Photon()
+ * app.use(binaryMiddleware())
+ *
+ * app.get('/api/data', (c) => c.json({ items: [1, 2, 3] }))
+ * ```
+ *
+ * @performance
+ * - CBOR encoding is ~2-3x faster than JSON.stringify for large objects.
+ * - Binary format reduces payload size by 20-40% on average.
+ * - Optimized to read body directly without clone(), saving ~30% overhead.
+ */
+export declare const binaryMiddleware: () => MiddlewareHandler;

package/dist/photon/src/middleware/htmx.d.ts

@@ -0,0 +1,39 @@
+import type { MiddlewareHandler } from 'hono';
+/**
+ * HTMX Middleware for Photon.
+ *
+ * Automatically detects HTMX requests and populates the context with
+ * HTMX-specific headers and state.
+ *
+ * @remarks
+ * This middleware enables hypermedia-driven UIs by providing first-class
+ * support for HTMX. It allows handlers to easily distinguish between
+ * full-page loads and partial updates.
+ *
+ * @returns A Hono middleware handler that populates HTMX context variables.
+ *
+ * @example
+ * ```typescript
+ * import { Photon } from '@gravito/photon'
+ * import { htmxMiddleware } from '@gravito/photon/middleware/htmx'
+ *
+ * const app = new Photon()
+ * app.use(htmxMiddleware())
+ *
+ * app.get('/search', async (c) => {
+ *   // Check if request is from HTMX
+ *   if (c.get('htmx')) {
+ *     return c.html('<div>Search results...</div>')
+ *   }
+ *
+ *   return c.html('<html>...</html>')
+ * })
+ * ```
+ *
+ * @context_variables
+ * - `htmx`: Boolean indicating if the request is an HTMX request.
+ * - `htmx.boosted`: Boolean indicating if the request was boosted.
+ * - `htmx.target`: The ID of the target element.
+ * - `htmx.trigger`: The ID of the trigger element.
+ */
+export declare const htmxMiddleware: () => MiddlewareHandler;

package/dist/photon/src/middleware/ratelimit.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Rate Limiting Middleware for Photon
+ *
+ * Provides token bucket and sliding window rate limiting strategies.
+ * Supports memory-based and Redis-based storage backends.
+ *
+ * @module @gravito/photon/middleware/ratelimit
+ * @since 1.0.0
+ */
+import type { Context, MiddlewareHandler } from '@gravito/photon';
+export interface RateLimitConfig {
+    /**
+     * Maximum number of requests allowed within the time window
+     * @default 100
+     */
+    maxRequests: number;
+    /**
+     * Time window in milliseconds
+     * @default 60000 (1 minute)
+     */
+    windowMs: number;
+    /**
+     * Strategy for rate limiting
+     * - 'token-bucket': Smooth rate limiting with token refill
+     * - 'sliding-window': Time-based window that slides continuously
+     * @default 'token-bucket'
+     */
+    strategy?: 'token-bucket' | 'sliding-window';
+    /**
+     * Custom key generator function
+     * @default (c) => c.req.header('x-forwarded-for') || c.req.header('x-real-ip') || 'unknown'
+     */
+    keyGenerator?: (c: Context) => string | Promise<string>;
+    /**
+     * Storage backend for rate limit state
+     * @default new MemoryStore()
+     */
+    store?: RateLimitStore;
+    /**
+     * Custom handler for rate-limited requests
+     * @default (c) => c.json({ error: 'Too Many Requests', retryAfter: <seconds> }, 429)
+     */
+    onRateLimitExceeded?: (c: Context, retryAfter: number) => Response | Promise<Response>;
+    /**
+     * Skip rate limiting for certain requests
+     * @default undefined
+     */
+    skip?: (c: Context) => boolean | Promise<boolean>;
+    /**
+     * Custom headers to include in responses
+     * @default true
+     */
+    standardHeaders?: boolean;
+    /**
+     * Include draft RateLimit headers (RateLimit-*)
+     * @default false
+     */
+    draftHeaders?: boolean;
+}
+export interface RateLimitStore {
+    /**
+     * Increment request count and return current state
+     */
+    increment(key: string): Promise<RateLimitState>;
+    /**
+     * Reset the rate limit for a key
+     */
+    reset(key: string): Promise<void>;
+    /**
+     * Get current state without incrementing
+     */
+    get(key: string): Promise<RateLimitState | null>;
+}
+export interface RateLimitState {
+    /**
+     * Number of requests made in current window
+     */
+    count: number;
+    /**
+     * Timestamp when the window expires (ms)
+     */
+    resetTime: number;
+    /**
+     * Remaining requests allowed
+     */
+    remaining: number;
+}
+export declare class MemoryStore implements RateLimitStore {
+    private config;
+    private store;
+    private cleanupInterval;
+    constructor(config: {
+        maxRequests: number;
+        windowMs: number;
+    }, cleanupIntervalMs?: number);
+    increment(key: string): Promise<RateLimitState>;
+    reset(key: string): Promise<void>;
+    get(key: string): Promise<RateLimitState | null>;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}
+/**
+ * Create a rate limiting middleware
+ *
+ * @example
+ * ```typescript
+ * import { Photon } from '@gravito/photon'
+ * import { rateLimit } from '@gravito/photon/middleware'
+ *
+ * const app = new Photon()
+ *
+ * // Basic usage: 100 requests per minute
+ * app.use('*', rateLimit({ maxRequests: 100, windowMs: 60000 }))
+ *
+ * // Per-user rate limiting
+ * app.use('/api/*', rateLimit({
+ *   maxRequests: 50,
+ *   windowMs: 60000,
+ *   keyGenerator: (c) => {
+ *     const userId = c.get('userId')
+ *     return userId || c.req.header('x-forwarded-for') || 'anonymous'
+ *   }
+ * }))
+ * ```
+ */
+export declare function rateLimit(config: RateLimitConfig): MiddlewareHandler;
+/**
+ * Convenience factory: Create rate limiter with common presets
+ */
+export declare const createRateLimiter: {
+    /**
+     * Strict: 10 requests per minute
+     */
+    strict: (overrides?: Partial<RateLimitConfig>) => MiddlewareHandler;
+    /**
+     * Moderate: 60 requests per minute
+     */
+    moderate: (overrides?: Partial<RateLimitConfig>) => MiddlewareHandler;
+    /**
+     * Lenient: 100 requests per minute
+     */
+    lenient: (overrides?: Partial<RateLimitConfig>) => MiddlewareHandler;
+    /**
+     * API: 1000 requests per hour
+     */
+    api: (overrides?: Partial<RateLimitConfig>) => MiddlewareHandler;
+    /**
+     * Auth: 5 attempts per 15 minutes (for login endpoints)
+     */
+    auth: (overrides?: Partial<RateLimitConfig>) => MiddlewareHandler;
+};
+/**
+ * Export convenience preset
+ */
+export { createRateLimiter as rateLimiter };

package/dist/photon/src/openapi.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file packages/photon/src/openapi.ts
+ * @module @gravito/photon/openapi
+ * @description OpenAPI (Swagger) integration for Photon
+ */
+import type { RouteConfig } from '@hono/zod-openapi';
+import { createRoute, OpenAPIHono } from '@hono/zod-openapi';
+import { z } from 'zod';
+/**
+ * Photon Open API Class
+ * Extends OpenAPIHono to provide a seamless OpenAPI integration.
+ */
+export declare class PhotonOpenAPI extends OpenAPIHono {
+    /**
+     * Helper to create a fully typed route definition.
+     */
+    static route(config: RouteConfig): RouteConfig;
+}
+export { createRoute, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/echo",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Enterprise-grade webhook handling for Gravito. Secure receiving and reliable sending.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -19,10 +19,12 @@
   ],
   "scripts": {
     "build": "bun run build.ts",
-    "test": "bun test",
+    "test": "bun test --timeout=10000",
+    "test:unit": "bun test tests/unit",
+    "test:integration": "test $(find tests -name '*.integration.test.ts' 2>/dev/null | wc -l) -gt 0 && find tests -name '*.integration.test.ts' -print0 | xargs -0 bun test --timeout=10000 || echo 'No integration tests found'",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
-    "test:coverage": "bun test --coverage --coverage-threshold=80",
-    "test:ci": "bun test --coverage --coverage-threshold=80"
+    "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
+    "test:ci": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts"
   },
   "keywords": [
     "gravito",
@@ -50,4 +52,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}