@spikard/node 0.9.0 → 0.10.1

package/dist/index.d.mts

@@ -0,0 +1,400 @@
+interface StreamingResponseInit {
+    statusCode?: number;
+    headers?: Record<string, string>;
+}
+declare const STREAM_HANDLE_PROP: "__spikard_stream_handle";
+type StreamChunk = JsonValue | string | Buffer | Uint8Array | ArrayBuffer | ArrayBufferView | null | undefined;
+type ChunkIterator = AsyncIterator<StreamChunk> & AsyncIterable<StreamChunk>;
+type StreamingHandle = {
+    kind: "native";
+    handle: number;
+    init: StreamingResponseInit;
+} | {
+    kind: "js";
+    iterator: ChunkIterator;
+    init: StreamingResponseInit;
+};
+declare class StreamingResponse {
+    readonly [STREAM_HANDLE_PROP]: StreamingHandle;
+    constructor(stream: AsyncIterable<StreamChunk> | AsyncIterator<StreamChunk>, init?: StreamingResponseInit);
+}
+
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [Key in string]: JsonValue;
+};
+type JsonRecord = Record<string, JsonValue>;
+type MaybePromise<T> = T | Promise<T>;
+interface Base64EncodedBody {
+    __spikard_base64__: string;
+}
+type HandlerBody = JsonValue | Base64EncodedBody | null;
+interface StructuredHandlerResponse {
+    status?: number;
+    statusCode?: number;
+    headers?: Record<string, string>;
+    body?: HandlerBody;
+}
+type HandlerResult = StructuredHandlerResponse | JsonValue | StreamingResponse | undefined;
+type HandlerFunction<TReturn extends HandlerResult = HandlerResult> = (request: Request) => MaybePromise<TReturn>;
+type NativeHandlerFunction<TReturn extends HandlerResult = HandlerResult> = (requestJson: string) => MaybePromise<TReturn | string>;
+type WebSocketHandler = (message: unknown) => MaybePromise<unknown>;
+interface WebSocketOptions {
+    onConnect?: () => MaybePromise<void>;
+    onDisconnect?: () => MaybePromise<void>;
+    messageSchema?: unknown;
+    responseSchema?: unknown;
+    handlerName?: string;
+}
+
+interface Request {
+    method: string;
+    path: string;
+    params: Record<string, string>;
+    pathParams: Record<string, string>;
+    query: Record<string, string>;
+    queryParams: Record<string, string>;
+    headers: Record<string, string>;
+    cookies: Record<string, string>;
+    body: Buffer | null;
+    dependencies: Record<string, unknown> | undefined;
+    json<T = JsonValue>(): T;
+    form(): Record<string, string>;
+}
+
+interface CompressionConfig {
+    gzip?: boolean;
+    brotli?: boolean;
+    minSize?: number;
+    quality?: number;
+}
+interface RateLimitConfig {
+    perSecond: number;
+    burst: number;
+    ipBased?: boolean;
+}
+interface JwtConfig {
+    secret: string;
+    algorithm?: string;
+    audience?: string[];
+    issuer?: string;
+    leeway?: number;
+}
+interface ApiKeyConfig {
+    keys: string[];
+    headerName?: string;
+}
+interface ContactInfo {
+    name?: string;
+    email?: string;
+    url?: string;
+}
+interface LicenseInfo {
+    name: string;
+    url?: string;
+}
+interface ServerInfo {
+    url: string;
+    description?: string;
+}
+interface SecuritySchemeInfo {
+    type: "http" | "apiKey";
+    scheme?: string;
+    bearerFormat?: string;
+    location?: "header" | "query" | "cookie";
+    name?: string;
+}
+interface OpenApiConfig {
+    enabled?: boolean;
+    title?: string;
+    version?: string;
+    description?: string;
+    swaggerUiPath?: string;
+    redocPath?: string;
+    openapiJsonPath?: string;
+    contact?: ContactInfo;
+    license?: LicenseInfo;
+    servers?: ServerInfo[];
+    securitySchemes?: Record<string, SecuritySchemeInfo>;
+}
+interface StaticFilesConfig {
+    directory: string;
+    routePrefix: string;
+    indexFile?: boolean;
+    cacheControl?: string;
+}
+interface ServerConfig {
+    host?: string;
+    port?: number;
+    workers?: number;
+    enableRequestId?: boolean;
+    maxBodySize?: number | null;
+    requestTimeout?: number | null;
+    compression?: CompressionConfig | null;
+    rateLimit?: RateLimitConfig | null;
+    jwtAuth?: JwtConfig | null;
+    apiKeyAuth?: ApiKeyConfig | null;
+    staticFiles?: StaticFilesConfig[];
+    gracefulShutdown?: boolean;
+    shutdownTimeout?: number;
+    openapi?: OpenApiConfig | null;
+}
+
+interface ServerOptions {
+    host?: string;
+    port?: number;
+}
+declare function runServer(app: SpikardApp, config?: ServerConfig | ServerOptions): void;
+
+type DependencyValue = unknown;
+type DependencyFactory = (dependencies: Record<string, DependencyValue>) => MaybePromise<DependencyValue>;
+interface DependencyOptions {
+    dependsOn?: string[];
+    singleton?: boolean;
+    cacheable?: boolean;
+}
+interface DependencyDescriptor {
+    isFactory: boolean;
+    value?: DependencyValue | undefined;
+    factory?: DependencyFactory | undefined;
+    dependsOn: string[];
+    singleton: boolean;
+    cacheable: boolean;
+}
+type LifecycleHookPayload = Request | StructuredHandlerResponse;
+type LifecycleHookFunction = (payload: LifecycleHookPayload) => MaybePromise<LifecycleHookPayload>;
+interface LifecycleHooks {
+    onRequest: LifecycleHookFunction[];
+    preValidation: LifecycleHookFunction[];
+    preHandler: LifecycleHookFunction[];
+    onResponse: LifecycleHookFunction[];
+    onError: LifecycleHookFunction[];
+}
+declare class Spikard implements SpikardApp {
+    routes: RouteMetadata[];
+    handlers: Record<string, HandlerFunction | NativeHandlerFunction>;
+    websocketRoutes: RouteMetadata[];
+    websocketHandlers: Record<string, Record<string, unknown>>;
+    lifecycleHooks: LifecycleHooks;
+    dependencies: Record<string, DependencyDescriptor>;
+    addRoute(metadata: RouteMetadata, handler: HandlerFunction | NativeHandlerFunction): void;
+    websocket(path: string, handler: WebSocketHandler, options?: WebSocketOptions): void;
+    run(options?: ServerOptions): void;
+    onRequest(hook: LifecycleHookFunction): LifecycleHookFunction;
+    preValidation(hook: LifecycleHookFunction): LifecycleHookFunction;
+    preHandler(hook: LifecycleHookFunction): LifecycleHookFunction;
+    onResponse(hook: LifecycleHookFunction): LifecycleHookFunction;
+    onError(hook: LifecycleHookFunction): LifecycleHookFunction;
+    provide(key: string, valueOrFactory: DependencyValue | DependencyFactory, options?: DependencyOptions): this;
+    getLifecycleHooks(): LifecycleHooks;
+}
+
+declare function run(work: () => void | Promise<void>): void;
+
+declare const background_run: typeof run;
+declare namespace background {
+  export { background_run as run };
+}
+
+type GrpcMetadata = Record<string, string>;
+interface GrpcRequest {
+    serviceName: string;
+    methodName: string;
+    payload: Buffer;
+    metadata: GrpcMetadata;
+}
+interface GrpcResponse {
+    payload: Buffer;
+    metadata?: GrpcMetadata;
+}
+interface GrpcHandler {
+    handleRequest(request: GrpcRequest): Promise<GrpcResponse>;
+}
+declare enum GrpcStatusCode {
+    OK = 0,
+    CANCELLED = 1,
+    UNKNOWN = 2,
+    INVALID_ARGUMENT = 3,
+    DEADLINE_EXCEEDED = 4,
+    NOT_FOUND = 5,
+    ALREADY_EXISTS = 6,
+    PERMISSION_DENIED = 7,
+    RESOURCE_EXHAUSTED = 8,
+    FAILED_PRECONDITION = 9,
+    ABORTED = 10,
+    OUT_OF_RANGE = 11,
+    UNIMPLEMENTED = 12,
+    INTERNAL = 13,
+    UNAVAILABLE = 14,
+    DATA_LOSS = 15,
+    UNAUTHENTICATED = 16
+}
+declare class GrpcError extends Error {
+    readonly code: GrpcStatusCode;
+    constructor(code: GrpcStatusCode, message: string);
+}
+interface GrpcServiceConfig {
+    serviceName: string;
+    handler: GrpcHandler;
+}
+type UnaryHandlerResult<TResponse> = TResponse | {
+    response: TResponse;
+    metadata?: Record<string, string>;
+};
+declare function createUnaryHandler<TRequest, TResponse>(methodName: string, handler: (request: TRequest, metadata: Record<string, string>) => Promise<UnaryHandlerResult<TResponse>>, requestType: {
+    decode(buffer: Uint8Array): TRequest;
+}, responseType: {
+    encode(message: TResponse): {
+        finish(): Uint8Array;
+    };
+}): GrpcHandler;
+declare function createServiceHandler(methods: Record<string, GrpcHandler>): GrpcHandler;
+
+declare function wrapHandler(handler: HandlerFunction): NativeHandlerFunction;
+declare function wrapBodyHandler<TBody = unknown>(handler: (body: TBody, request: Request) => MaybePromise<HandlerResult>): NativeHandlerFunction;
+
+type Query<T> = T;
+type Path<T> = T;
+type Body<T> = T;
+declare function QueryDefault<T>(value: T): T;
+
+interface RouteOptions {
+    methods?: string | string[];
+    bodySchema?: JsonSchema;
+    responseSchema?: JsonSchema;
+    parameterSchema?: JsonSchema;
+    cors?: CorsConfig;
+}
+type RouteHandler = (request: Request) => MaybePromise<HandlerResult>;
+declare function route(path: string, options?: RouteOptions): (handler: RouteHandler) => RouteHandler;
+declare function get(path: string, options?: Omit<RouteOptions, "methods">): (handler: RouteHandler) => RouteHandler;
+declare function post(path: string, options?: Omit<RouteOptions, "methods">): (handler: RouteHandler) => RouteHandler;
+declare function put(path: string, options?: Omit<RouteOptions, "methods">): (handler: RouteHandler) => RouteHandler;
+declare function del(path: string, options?: Omit<RouteOptions, "methods">): (handler: RouteHandler) => RouteHandler;
+declare function patch(path: string, options?: Omit<RouteOptions, "methods">): (handler: RouteHandler) => RouteHandler;
+
+interface NativeTestResponse {
+    statusCode: number;
+    headers(): Record<string, string>;
+    text(): string;
+    json<T>(): T;
+    bytes(): Buffer;
+    graphqlData(): unknown;
+    graphqlErrors(): Array<Record<string, unknown>>;
+}
+interface WebSocketTestConnection {
+    sendText(text: string): Promise<void>;
+    sendJson(obj: unknown): Promise<void>;
+    receiveText(): Promise<string>;
+    receiveJson(): Promise<unknown>;
+    receiveBytes(): Promise<Buffer>;
+    receiveMessage(): Promise<unknown>;
+    close(): Promise<void>;
+}
+type TestResponse = NativeTestResponse;
+interface MultipartFile {
+    name: string;
+    filename?: string;
+    content: string;
+    contentType?: string;
+}
+interface RequestOptions {
+    headers?: Record<string, string>;
+    json?: JsonValue;
+    form?: Record<string, JsonValue>;
+    multipart?: {
+        fields?: Record<string, JsonValue>;
+        files?: MultipartFile[];
+    };
+}
+declare class TestClient {
+    readonly app: SpikardApp;
+    private nativeClient;
+    private looksLikeStringHandler;
+    constructor(app: SpikardApp);
+    get(path: string, headers?: Record<string, string>): Promise<TestResponse>;
+    post(path: string, options?: RequestOptions): Promise<TestResponse>;
+    put(path: string, options?: RequestOptions): Promise<TestResponse>;
+    delete(path: string, headers?: Record<string, string>): Promise<TestResponse>;
+    patch(path: string, options?: RequestOptions): Promise<TestResponse>;
+    head(path: string, headers?: Record<string, string>): Promise<TestResponse>;
+    options(path: string, options?: RequestOptions): Promise<TestResponse>;
+    trace(path: string, options?: RequestOptions): Promise<TestResponse>;
+    private buildHeaders;
+    private buildBody;
+    websocketConnect(path: string): Promise<WebSocketTestConnection>;
+    graphql(query: string, variables?: Record<string, unknown> | null, operationName?: string | null): Promise<TestResponse>;
+    graphqlWithStatus(query: string, variables?: Record<string, unknown> | null, operationName?: string | null): Promise<{
+        status: number;
+        statusCode: number;
+        headers: string;
+        bodyText: string;
+    }>;
+    cleanup(): Promise<void>;
+}
+
+declare class UploadFile {
+    readonly filename: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly headers: Record<string, string>;
+    private readonly _content;
+    private _position;
+    constructor(filename: string, content: Buffer, contentType?: string | null, size?: number | null, headers?: Record<string, string> | null);
+    read(size?: number): Buffer;
+    readAsync(size?: number): Promise<Buffer>;
+    text(): string;
+    textAsync(): Promise<string>;
+    seek(offset: number, whence?: number): number;
+    seekAsync(offset: number, whence?: number): Promise<number>;
+    tell(): number;
+    getBuffer(): Buffer;
+    close(): void;
+    closeAsync(): Promise<void>;
+    toString(): string;
+    toJSON(): Record<string, unknown>;
+}
+
+interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema | JsonSchema[];
+    enum?: JsonValue[];
+    [key: string]: JsonSchema | JsonSchema[] | JsonValue | JsonValue[] | string | number | boolean | undefined;
+}
+interface CorsConfig {
+    allow_origin?: string | string[];
+    allow_methods?: string[];
+    allow_headers?: string[];
+    allow_credentials?: boolean;
+    max_age?: number;
+}
+interface FileParam {
+    name: string;
+    required?: boolean;
+    max_size?: number;
+    allowed_types?: string[];
+}
+interface RouteMetadata {
+    method: string;
+    path: string;
+    handler_name: string;
+    request_schema?: JsonSchema | undefined;
+    response_schema?: JsonSchema | undefined;
+    parameter_schema?: JsonSchema | undefined;
+    file_params?: FileParam[] | undefined;
+    is_async: boolean;
+    cors?: CorsConfig | undefined;
+}
+interface SpikardApp {
+    routes: RouteMetadata[];
+    handlers: Record<string, HandlerFunction | NativeHandlerFunction>;
+    websocketRoutes?: RouteMetadata[];
+    websocketHandlers?: Record<string, Record<string, unknown>>;
+    config?: ServerConfig;
+    lifecycleHooks?: Partial<LifecycleHooks>;
+    dependencies?: Record<string, unknown>;
+}
+
+export { type ApiKeyConfig, type Base64EncodedBody, type Body, type CompressionConfig, type ContactInfo, type CorsConfig, type DependencyFactory, type DependencyOptions, type DependencyValue, type FileParam, GrpcError, type GrpcHandler, type GrpcMetadata, type GrpcRequest, type GrpcResponse, type GrpcServiceConfig, GrpcStatusCode, type HandlerFunction, type HandlerResult, type JsonPrimitive, type JsonRecord, type JsonSchema, type JsonValue, type JwtConfig, type LicenseInfo, type LifecycleHookFunction, type LifecycleHooks, type MaybePromise, type NativeHandlerFunction, type OpenApiConfig, type Path, type Query, QueryDefault, type RateLimitConfig, type Request, type RouteMetadata, type RouteOptions, type SecuritySchemeInfo, type ServerConfig, type ServerInfo, type ServerOptions, Spikard, type SpikardApp, type StaticFilesConfig, StreamingResponse, type StreamingResponseInit, type StructuredHandlerResponse, TestClient, type TestResponse, UploadFile, type WebSocketHandler, type WebSocketOptions, background, createServiceHandler, createUnaryHandler, del, get, patch, post, put, route, runServer, wrapBodyHandler, wrapHandler };