@buenojs/bueno 0.8.9 → 0.8.11

package/dist/graphql/subscription-handler.js

@@ -0,0 +1,201 @@
+/**
+ * GraphQL Subscription Handler
+ *
+ * Implements the graphql-transport-ws protocol over Bun's native WebSocket.
+ * Registered via app.setWebSocketHandler() so subscriptions run on the same
+ * port as the HTTP server — no separate port needed.
+ *
+ * Protocol spec: https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md
+ *
+ * ## Usage
+ * Automatically configured by GraphQLModule.setup() when subscriptions: true.
+ * Requires an engine with supportsSubscriptions = true (e.g. GraphQLJsAdapter).
+ */
+// ============= Subscription Handler =============
+export class SubscriptionHandler {
+    engine;
+    engineSchema;
+    graphqlPath;
+    container;
+    globalGuards;
+    globalInterceptors;
+    connections = new Map();
+    constructor(engine, engineSchema, graphqlPath, container, globalGuards, globalInterceptors) {
+        this.engine = engine;
+        this.engineSchema = engineSchema;
+        this.graphqlPath = graphqlPath;
+        this.container = container;
+        this.globalGuards = globalGuards;
+        this.globalInterceptors = globalInterceptors;
+    }
+    /**
+     * Returns a Bun WebSocketHandler to register on the server via app.setWebSocketHandler().
+     * Attaches an __upgradeHandler so Application.listen() can delegate WebSocket upgrades.
+     */
+    getWebSocketConfig() {
+        const upgradeHandler = this.handleUpgrade.bind(this);
+        return {
+            __upgradeHandler: upgradeHandler,
+            open: (ws) => {
+                this.connections.set(ws.data.connectionId, {
+                    subscriptions: new Map(),
+                    initialized: false,
+                });
+            },
+            message: async (ws, raw) => {
+                try {
+                    const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+                    const msg = JSON.parse(text);
+                    await this.handleMessage(ws, msg);
+                }
+                catch (err) {
+                    this.send(ws, {
+                        type: "error",
+                        id: "",
+                        payload: [{ message: `Protocol error: ${err.message}` }],
+                    });
+                }
+            },
+            close: (ws) => {
+                const state = this.connections.get(ws.data.connectionId);
+                if (state) {
+                    // Cancel all active subscriptions
+                    for (const sub of state.subscriptions.values()) {
+                        sub.generator.return?.(undefined);
+                    }
+                    this.connections.delete(ws.data.connectionId);
+                }
+            },
+            error: (ws, error) => {
+                console.error("[GraphQL WS] WebSocket error:", error);
+            },
+        };
+    }
+    /**
+     * Middleware-like upgrade handler.
+     * Call this from the app's fetch function for WebSocket upgrade requests.
+     * Returns a Response if not a GraphQL WS path, undefined if upgraded.
+     */
+    handleUpgrade(req, server) {
+        const url = new URL(req.url);
+        if (url.pathname !== this.graphqlPath) {
+            return undefined; // Not our path — let normal routing handle it
+        }
+        const protocol = req.headers.get("sec-websocket-protocol") ?? "";
+        if (!protocol.includes("graphql-transport-ws")) {
+            return new Response("Unsupported WebSocket protocol", { status: 426 });
+        }
+        const connectionId = crypto.randomUUID();
+        const upgraded = server.upgrade(req, {
+            headers: {
+                "Sec-WebSocket-Protocol": "graphql-transport-ws",
+            },
+            data: { connectionId },
+        });
+        return upgraded ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
+    }
+    // ============= Message Handlers =============
+    async handleMessage(ws, msg) {
+        const state = this.connections.get(ws.data.connectionId);
+        if (!state)
+            return;
+        switch (msg.type) {
+            case "connection_init":
+                if (state.initialized) {
+                    // Already initialized — send error and close
+                    ws.close(4429, "Too many initialisation requests");
+                    return;
+                }
+                state.initialized = true;
+                this.send(ws, { type: "connection_ack" });
+                break;
+            case "subscribe":
+                if (!state.initialized) {
+                    ws.close(4401, "Unauthorized: connection not initialized");
+                    return;
+                }
+                if (state.subscriptions.has(msg.id)) {
+                    ws.close(4409, `Subscriber for ${msg.id} already exists`);
+                    return;
+                }
+                await this.handleSubscribe(ws, state, msg);
+                break;
+            case "complete":
+                if (msg.id) {
+                    const sub = state.subscriptions.get(msg.id);
+                    if (sub) {
+                        sub.generator.return?.(undefined);
+                        state.subscriptions.delete(msg.id);
+                    }
+                }
+                break;
+        }
+    }
+    async handleSubscribe(ws, state, msg) {
+        if (!this.engine.subscribe) {
+            this.send(ws, {
+                type: "error",
+                id: msg.id,
+                payload: [
+                    {
+                        message: "Subscriptions are not supported by the configured GraphQL engine. " +
+                            "Use GraphQLJsAdapter for subscription support.",
+                    },
+                ],
+            });
+            return;
+        }
+        const context = {
+            request: new Request(`ws://localhost${this.graphqlPath}`),
+            user: undefined,
+            httpContext: null,
+        };
+        let generator;
+        try {
+            generator = await this.engine.subscribe(this.engineSchema, msg.payload.query, msg.payload.variables ?? {}, context, msg.payload.operationName);
+        }
+        catch (err) {
+            this.send(ws, {
+                type: "error",
+                id: msg.id,
+                payload: [{ message: err.message }],
+            });
+            return;
+        }
+        state.subscriptions.set(msg.id, { generator });
+        // Stream results
+        (async () => {
+            try {
+                for await (const result of generator) {
+                    if (!state.subscriptions.has(msg.id))
+                        break; // Cancelled
+                    this.send(ws, {
+                        type: "next",
+                        id: msg.id,
+                        payload: result,
+                    });
+                }
+                // Subscription completed
+                this.send(ws, { type: "complete", id: msg.id });
+                state.subscriptions.delete(msg.id);
+            }
+            catch (err) {
+                this.send(ws, {
+                    type: "error",
+                    id: msg.id,
+                    payload: [{ message: err.message }],
+                });
+                state.subscriptions.delete(msg.id);
+            }
+        })();
+    }
+    send(ws, msg) {
+        try {
+            ws.send(JSON.stringify(msg));
+        }
+        catch {
+            // Connection may have closed — ignore
+        }
+    }
+}
+//# sourceMappingURL=subscription-handler.js.map

package/dist/graphql/subscription-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-handler.js","sourceRoot":"","sources":["../../src/graphql/subscription-handler.ts"],"names":[],"mappings":"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"}

package/dist/graphql/types.d.ts

@@ -0,0 +1,252 @@
+/**
+ * GraphQL Module Types
+ *
+ * Core type definitions for the Bueno GraphQL integration layer.
+ */
+export type Constructor<T = unknown> = new (...args: unknown[]) => T;
+/**
+ * Represents a GraphQL scalar type via its JS constructor.
+ * Usage: () => String, () => Number, () => Boolean, () => GraphQLID
+ */
+export type GraphQLScalar = StringConstructor | NumberConstructor | BooleanConstructor | typeof GraphQLID | typeof GraphQLInt | typeof GraphQLFloat;
+/**
+ * A thunk that returns a type constructor or array of constructors.
+ * Used to avoid circular reference issues in type definitions.
+ *
+ * @example
+ * () => String        // GraphQL String scalar
+ * () => Number        // GraphQL Float scalar
+ * () => [User]        // [User!]! list
+ * () => User          // User object type
+ */
+export type TypeFn = () => Constructor | Constructor[] | GraphQLScalar;
+/**
+ * Sentinel class representing GraphQL ID scalar.
+ * Usage: @Field(() => GraphQLID)
+ */
+export declare class GraphQLID {
+    static readonly __type = "ID";
+}
+/**
+ * Sentinel class representing GraphQL Int scalar.
+ * Usage: @Field(() => GraphQLInt)
+ */
+export declare class GraphQLInt {
+    static readonly __type = "Int";
+}
+/**
+ * Sentinel class representing GraphQL Float scalar.
+ * Usage: @Field(() => GraphQLFloat)
+ */
+export declare class GraphQLFloat {
+    static readonly __type = "Float";
+}
+/** Options for @Field decorator */
+export interface FieldDecoratorOptions {
+    /** Whether the field can be null (default: false → non-null) */
+    nullable?: boolean;
+    /** Human-readable description */
+    description?: string;
+    /** Deprecation reason */
+    deprecationReason?: string;
+    /** Default value for input types */
+    defaultValue?: unknown;
+}
+/** Options for @Query/@Mutation/@Subscription decorators */
+export interface FieldOptions extends FieldDecoratorOptions {
+    /** GraphQL field name override (default: method name) */
+    name?: string;
+}
+/** Metadata stored per @Field-decorated property */
+export interface FieldMetadata {
+    propertyKey: string;
+    typeFn: TypeFn;
+    nullable: boolean;
+    description?: string;
+    deprecationReason?: string;
+    defaultValue?: unknown;
+}
+/** Metadata for a single resolver method parameter */
+export interface ParamMetadata {
+    index: number;
+    kind: "args" | "argsObject" | "context";
+    /** For @Args('name') — the specific argument name */
+    argName?: string;
+    /** For @Args('name', InputType) — the input object type */
+    inputTypeFn?: TypeFn;
+}
+/** Metadata stored per @Query/@Mutation/@Subscription method */
+export interface ResolverFieldMetadata {
+    /** Actual method name on the class */
+    methodName: string;
+    /** GraphQL field name (defaults to methodName) */
+    fieldName: string;
+    typeFn: TypeFn;
+    kind: "query" | "mutation" | "subscription";
+    nullable: boolean;
+    description?: string;
+    deprecationReason?: string;
+    paramMetadata: ParamMetadata[];
+}
+/** Metadata stored per @Resolver-decorated class */
+export interface ResolverClassMetadata {
+    /** GraphQL type name (default: class name) */
+    name: string;
+}
+/** Metadata stored per @ObjectType / @InputType class */
+export interface TypeClassMetadata {
+    name: string;
+    kind: "object" | "input";
+    description?: string;
+}
+/** A single resolvable field in the built schema */
+export interface ResolvedField {
+    resolverInstance: unknown;
+    methodName: string;
+    paramMetadata: ParamMetadata[];
+    typeFn: TypeFn;
+    nullable: boolean;
+}
+/** Internal schema representation consumed by the built-in engine */
+export interface ResolvedSchema {
+    queryFields: Map<string, ResolvedField>;
+    mutationFields: Map<string, ResolvedField>;
+    subscriptionFields: Map<string, ResolvedField>;
+}
+/** Context available inside resolver methods */
+export interface GraphQLContext {
+    /** The original HTTP Request */
+    request: Request;
+    /** Authenticated user (set by auth guards via context.set('user', ...)) */
+    user?: unknown;
+    /** Reference to the HTTP Context for advanced use */
+    httpContext: unknown;
+    /** Allow arbitrary values */
+    [key: string]: unknown;
+}
+/** A GraphQL error entry in the response */
+export interface GraphQLError {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown>;
+}
+/** The GraphQL response envelope */
+export interface GraphQLResult {
+    data?: Record<string, unknown> | null;
+    errors?: GraphQLError[];
+}
+/**
+ * Pluggable GraphQL execution engine.
+ * Implement this interface to use graphql-js, GraphQL Yoga, Mercurius, etc.
+ *
+ * @example
+ * ```typescript
+ * import * as graphqlJs from 'graphql';
+ * import { GraphQLJsAdapter } from '@buenojs/bueno/graphql';
+ *
+ * GraphQLModule.setup(app, {
+ *   engine: new GraphQLJsAdapter(graphqlJs),
+ *   resolvers: [UserResolver],
+ * });
+ * ```
+ */
+export interface GraphQLEngine {
+    /**
+     * Build the internal schema representation from resolver and type metadata.
+     * Returns an opaque schema object that is passed back to execute().
+     */
+    buildSchema(resolvers: ResolverFieldsByType, types: Map<string, FieldMetadata[]>, sdl: string): unknown;
+    /**
+     * Execute a GraphQL query or mutation.
+     */
+    execute(schema: unknown, query: string, variables: Record<string, unknown>, context: GraphQLContext, operationName?: string): Promise<GraphQLResult>;
+    /**
+     * Execute a GraphQL subscription (optional).
+     * Returns an async generator that yields results.
+     */
+    subscribe?(schema: unknown, query: string, variables: Record<string, unknown>, context: GraphQLContext, operationName?: string): Promise<AsyncGenerator<GraphQLResult>>;
+    /**
+     * Whether this engine supports introspection queries.
+     * Used to determine if the GraphQL Playground should be enabled.
+     */
+    readonly supportsIntrospection: boolean;
+    /**
+     * Whether this engine supports subscriptions.
+     */
+    readonly supportsSubscriptions: boolean;
+}
+/** Resolver fields organized by root type */
+export interface ResolverFieldsByType {
+    queries: Map<string, ResolvedField>;
+    mutations: Map<string, ResolvedField>;
+    subscriptions: Map<string, ResolvedField>;
+}
+/**
+ * Options passed to GraphQLModule.setup()
+ */
+export interface GraphQLModuleOptions {
+    /**
+     * Resolver classes to register.
+     * Dependencies are resolved from the DI container.
+     */
+    resolvers: Constructor[];
+    /**
+     * GraphQL engine adapter (default: built-in lightweight engine).
+     * Use GraphQLJsAdapter for full spec compliance.
+     */
+    engine?: GraphQLEngine;
+    /**
+     * HTTP path for the GraphQL endpoint (default: '/graphql').
+     */
+    path?: string;
+    /**
+     * Enable GraphiQL playground UI at GET <path>.
+     * Default: true when using an engine with supportsIntrospection,
+     *          false when using the built-in engine.
+     * Set to true to force-enable even with the built-in engine (with warning).
+     */
+    playground?: boolean;
+    /**
+     * Serve the SDL at GET <path>/schema (default: true).
+     */
+    introspection?: boolean;
+    /**
+     * Enable WebSocket subscriptions (default: false).
+     * Requires an engine with supportsSubscriptions.
+     */
+    subscriptions?: boolean;
+    /**
+     * Sync @Field metadata to the OpenAPI property store (default: false).
+     * Enables unified types: one class works for both GraphQL and REST/OpenAPI.
+     * Requires @buenojs/bueno/openapi to be in scope.
+     */
+    syncOpenAPI?: boolean;
+    /** Maximum query complexity score (default: 1000) */
+    complexityLimit?: number;
+    /** Maximum query depth (default: 10) */
+    maxDepth?: number;
+}
+/**
+ * GraphQL configuration added to BuenoConfig.
+ */
+export interface GraphQLConfig {
+    /** Enable GraphQL support (default: false) */
+    enabled?: boolean;
+    /** HTTP path (default: '/graphql') */
+    path?: string;
+    /** Enable playground (default: auto) */
+    playground?: boolean;
+    /** Enable introspection SDL endpoint (default: true) */
+    introspection?: boolean;
+    /** Maximum query complexity (default: 1000) */
+    complexityLimit?: number;
+    /** Maximum query depth (default: 10) */
+    maxDepth?: number;
+    /** Enable subscriptions (default: false) */
+    subscriptions?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/graphql/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/graphql/types.ts"],"names":[],"mappings":"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"}

package/dist/graphql/types.js

@@ -0,0 +1,28 @@
+/**
+ * GraphQL Module Types
+ *
+ * Core type definitions for the Bueno GraphQL integration layer.
+ */
+// ============= Scalar Sentinels =============
+/**
+ * Sentinel class representing GraphQL ID scalar.
+ * Usage: @Field(() => GraphQLID)
+ */
+export class GraphQLID {
+    static __type = "ID";
+}
+/**
+ * Sentinel class representing GraphQL Int scalar.
+ * Usage: @Field(() => GraphQLInt)
+ */
+export class GraphQLInt {
+    static __type = "Int";
+}
+/**
+ * Sentinel class representing GraphQL Float scalar.
+ * Usage: @Field(() => GraphQLFloat)
+ */
+export class GraphQLFloat {
+    static __type = "Float";
+}
+//# sourceMappingURL=types.js.map

package/dist/graphql/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/graphql/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgCH,+CAA+C;AAE/C;;;GAGG;AACH,MAAM,OAAO,SAAS;IACrB,MAAM,CAAU,MAAM,GAAG,IAAI,CAAC;;AAG/B;;;GAGG;AACH,MAAM,OAAO,UAAU;IACtB,MAAM,CAAU,MAAM,GAAG,KAAK,CAAC;;AAGhC;;;GAGG;AACH,MAAM,OAAO,YAAY;IACxB,MAAM,CAAU,MAAM,GAAG,OAAO,CAAC"}

package/dist/health/index.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Health Check System
+ *
+ * Provides health check endpoints for production monitoring:
+ * - /health (liveness probe) - Returns 200 if server is running
+ * - /ready (readiness probe) - Returns 200 only if all checks pass
+ */
+import type { Middleware } from "../middleware";
+/**
+ * Health check status
+ */
+export type HealthStatus = "healthy" | "unhealthy" | "degraded";
+/**
+ * Individual check result
+ */
+export interface CheckResult {
+    status: HealthStatus;
+    latency?: number;
+    message?: string;
+}
+/**
+ * Overall health check result
+ */
+export interface HealthCheckResult {
+    status: HealthStatus;
+    timestamp: string;
+    version?: string;
+    uptime?: number;
+    checks?: Record<string, CheckResult>;
+}
+/**
+ * Health check function type
+ */
+export type HealthCheckFn = () => Promise<CheckResult> | CheckResult;
+/**
+ * Options for individual health checks
+ */
+export interface CheckOptions {
+    /** Whether this check is critical for readiness (default: true) */
+    critical?: boolean;
+    /** Timeout in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Description of the check */
+    description?: string;
+}
+/**
+ * Options for health middleware
+ */
+export interface HealthMiddlewareOptions {
+    /** Path for liveness probe (default: /health) */
+    healthPath?: string;
+    /** Path for readiness probe (default: /ready) */
+    readyPath?: string;
+    /** Whether to expose metrics in response (default: true) */
+    exposeMetrics?: boolean;
+    /** Initial health checks to register */
+    checks?: Record<string, HealthCheckFn | {
+        fn: HealthCheckFn;
+        options?: CheckOptions;
+    }>;
+    /** Custom version string (default: from package.json) */
+    version?: string;
+}
+/**
+ * Database interface for built-in checker
+ */
+export interface DatabaseLike {
+    query?(sql: string): Promise<unknown>;
+    execute?(sql: string): Promise<unknown>;
+    healthCheck?(): Promise<boolean>;
+}
+/**
+ * Cache interface for built-in checker
+ */
+export interface CacheLike {
+    get?(key: string): Promise<unknown>;
+    set?(key: string, value: unknown): Promise<unknown>;
+    ping?(): Promise<unknown>;
+    healthCheck?(): Promise<boolean>;
+}
+/**
+ * Manages health checks for the application
+ */
+export declare class HealthCheckManager {
+    private checks;
+    private startTime;
+    private version;
+    constructor(version?: string);
+    /**
+     * Register a health check
+     */
+    registerCheck(name: string, checkFn: HealthCheckFn, options?: CheckOptions): this;
+    /**
+     * Remove a health check
+     */
+    removeCheck(name: string): boolean;
+    /**
+     * Get all registered check names
+     */
+    getCheckNames(): string[];
+    /**
+     * Check if a check is registered
+     */
+    hasCheck(name: string): boolean;
+    /**
+     * Run a single check with timeout
+     */
+    private runSingleCheck;
+    /**
+     * Execute all registered checks
+     */
+    runChecks(): Promise<Record<string, CheckResult>>;
+    /**
+     * Get liveness status (lightweight - no dependency checks)
+     */
+    getHealth(): HealthCheckResult;
+    /**
+     * Get readiness status (runs all checks)
+     */
+    getReadiness(): Promise<HealthCheckResult>;
+    /**
+     * Get uptime in seconds
+     */
+    getUptime(): number;
+    /**
+     * Reset start time (useful for testing)
+     */
+    resetStartTime(): void;
+}
+/**
+ * Create health check middleware
+ */
+export declare function createHealthMiddleware(options?: HealthMiddlewareOptions): {
+    middleware: Middleware;
+    manager: HealthCheckManager;
+};
+/**
+ * Create a database connectivity check
+ */
+export declare function createDatabaseCheck(db: DatabaseLike, options?: {
+    query?: string;
+    timeout?: number;
+}): HealthCheckFn;
+/**
+ * Create a cache connectivity check
+ */
+export declare function createCacheCheck(cache: CacheLike, options?: {
+    testKey?: string;
+    timeout?: number;
+}): HealthCheckFn;
+/**
+ * Create a custom health check with timeout
+ */
+export declare function createCustomCheck(checkFn: () => Promise<boolean> | boolean, options?: {
+    message?: string;
+    timeout?: number;
+}): HealthCheckFn;
+/**
+ * Create a TCP port check
+ */
+export declare function createTCPCheck(host: string, port: number, options?: {
+    timeout?: number;
+}): HealthCheckFn;
+/**
+ * Create an HTTP endpoint check
+ */
+export declare function createHTTPCheck(url: string, options?: {
+    expectedStatus?: number;
+    timeout?: number;
+    headers?: Record<string, string>;
+}): HealthCheckFn;
+/**
+ * Create a new health check manager
+ */
+export declare function createHealthManager(version?: string): HealthCheckManager;
+//# sourceMappingURL=index.d.ts.map