import type { BaseStream } from '../services/stream/base-stream.js';

export type RouteSendOptions = {
    /** Defaults to `response`; any other value sends an application event. */
    type?: string;

    /** Applies to normal responses. Defaults to 200, or 204 for undefined data. */
    statusCode?: number;
};

/**
 * Request-scoped application view over an underlying transport connection.
 *
 * The body and request ID are immutable for one dispatch. Subscription state and
 * connection lifetime are shared with other requests on the same connection.
 */
export interface RouteStream {
    /** Connection shared by every request on the same transport session. */
    readonly connection: BaseStream;

    readonly body: unknown;
    readonly streaming: boolean;
    readonly bidirectional: boolean;

    send(data: unknown, options?: RouteSendOptions): Promise<void>;
}

export type RouteHandler = (stream: RouteStream) => void | Promise<void>;

/** An exact application route with no transport-specific metadata. */
export type RouteDefinition = {
    /** Exact route name. Parameter and wildcard syntax are not supported. */
    url: string;
    handler: RouteHandler;
};

/** Supplies and validates routes during application startup. */
export interface RouteModule {
    getRoutes(): Promise<Array<RouteDefinition>>;
}