@gravito/ripple 3.0.0 → 3.1.0

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

@@ -0,0 +1,70 @@
+/**
+ * @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';

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/ripple/src/OrbitRipple.d.ts

@@ -0,0 +1,64 @@
+import type { GravitoOrbit, PlanetCore } from '@gravito/core';
+import { BroadcastManager } from './events/BroadcastManager';
+import { RippleServer } from './RippleServer';
+import type { RippleConfig } from './types';
+/**
+ * OrbitRipple integrates the Ripple WebSocket module into the Gravito framework.
+ *
+ * It handles the registration of the RippleServer in the IoC container,
+ * adds middleware for context access, and manages the server lifecycle.
+ *
+ * @example
+ * ```typescript
+ * import { PlanetCore } from '@gravito/core'
+ * import { OrbitRipple } from '@gravito/ripple'
+ *
+ * const core = new PlanetCore()
+ *
+ * // Install Ripple as an Orbit
+ * core.install(new OrbitRipple({
+ *   path: '/ws',
+ *   authorizer: async (channel, userId) => userId !== undefined
+ * }))
+ * ```
+ */
+export declare class OrbitRipple implements GravitoOrbit {
+    private server;
+    private config;
+    /**
+     * Create a new OrbitRipple.
+     *
+     * @param config - Ripple configuration options
+     */
+    constructor(config?: RippleConfig);
+    /**
+     * Install the orbit into the Gravito core.
+     *
+     * - Registers 'ripple' (RippleServer) and 'broadcast' (BroadcastManager) in the container.
+     * - Adds middleware to inject 'ripple' and 'broadcast' into GravitoContext.
+     * - Initializes the server and registers shutdown hooks.
+     *
+     * @param core - The PlanetCore instance
+     */
+    install(core: PlanetCore): void;
+    /**
+     * Get the underlying RippleServer instance.
+     *
+     * @returns The RippleServer instance
+     */
+    getServer(): RippleServer;
+    /**
+     * Get the WebSocket handler for Bun.serve.
+     *
+     * @returns The WebSocket handler object
+     */
+    getHandler(): import("./types").WebSocketHandlerConfig;
+}
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** RippleServer instance available in context */
+        ripple?: RippleServer;
+        /** BroadcastManager instance available in context */
+        broadcast?: BroadcastManager;
+    }
+}