@sigiljs/sigil
Version:
TypeScript-first Node.js HTTP framework offering schema-driven routing, modifier-based middleware, plugin extensibility, and flexible response templating
112 lines (111 loc) • 5.57 kB
TypeScript
import { RouteParams } from '@sigiljs/pathfinder';
import { ObjectSchema } from '@sigiljs/seal';
import { InferSchema } from '@sigiljs/seal/types';
import { ClientRequest } from '../index';
import { MergePayloads, ModifierConstructor, Route, RouteOptions } from '../route';
import { SigilPlugin, SigilPluginConstructor, SigilResponsesList } from './misc';
import { default as SigilRequestProcessor } from './sigil-request-processor';
import { InferMeta, RequestValidator, SigilOptions } from './types';
/**
* Main Sigil framework class that provides API for defining schemas,
* registering plugins, mounting routes, and starting the HTTP server.
* Extends SigilRequestProcessor to include routing and plugin management.
*
* @template T type of SigilOptions for runtime configuration.
*/
export default class Sigil<T extends Partial<SigilOptions> = Partial<SigilOptions>> extends SigilRequestProcessor<T> {
/**
* Static helper to pair a schema definition with optional metadata.
*/
defineSchema: typeof Sigil.defineSchema;
/**
* Static helper to pair a handler with optional metadata.
*/
defineHandler: typeof Sigil.defineHandler;
/**
* Constructs a new Sigil instance with given options.
*
* @param options partial SigilOptions to configure core behavior.
*/
constructor(options?: T);
/**
* Define request handler with metadata.
*
* TypeScript-only helper
*/
static defineHandler<Path extends string, Body extends Record<string, any> | [Record<string, any>, any], Headers extends Record<string, any> | [Record<string, any>, any], Query extends Record<string, any> | [Record<string, any>, any], Modifiers extends (readonly ModifierConstructor<any, any>[]) | undefined = undefined>(_: {
path?: Path;
body?: Body;
headers?: Headers;
query?: Query;
modifiers?: Modifiers;
}, callback: (request: ClientRequest<RouteParams<Path>, InferSchema<ObjectSchema<Body extends [Record<string, any>, any] ? Body[0] : Body>>, InferSchema<ObjectSchema<Headers extends [Record<string, any>, any] ? Headers[0] : Headers>>, InferSchema<ObjectSchema<Query extends [Record<string, any>, any] ? Query[0] : Query>>> & (Modifiers extends readonly ModifierConstructor<any, any>[] ? MergePayloads<Modifiers> : {}), response: SigilResponsesList, app: Sigil | null) => any): (request: ClientRequest<RouteParams<Path>, InferSchema<ObjectSchema<Body extends [Record<string, any>, any] ? Body[0] : Body>>, InferSchema<ObjectSchema<Headers extends [Record<string, any>, any] ? Headers[0] : Headers>>, InferSchema<ObjectSchema<Query extends [Record<string, any>, any] ? Query[0] : Query>>> & (Modifiers extends readonly ModifierConstructor<any, any>[] ? MergePayloads<Modifiers> : {}), response: SigilResponsesList, app: Sigil | null) => any;
/**
* Overload: define a schema without metadata.
*
* @param schema object mapping keys to BaseSchema instances.
* @returns tuple of schema and undefined metadata.
*/
static defineSchema<Schema extends RequestValidator, Meta extends InferMeta<Schema>>(schema: Schema): [
Schema & (Meta extends {
allowUnknown: true;
} ? {
[key: string]: any;
} : {}),
undefined
];
/**
* Overload: define a schema with metadata inference.
*
* @param schema object mapping keys to schema validators.
* @param meta inferred metadata for the schema.
* @returns tuple of schema and inferred metadata.
*/
static defineSchema<Schema extends RequestValidator, Meta extends InferMeta<Schema>>(schema: Schema, meta: Meta): [
Schema & (Meta extends {
allowUnknown: true;
} ? {
[key: string]: any;
} : {}),
Meta
];
/**
* Registers and configures a Sigil plugin.
* Attaches framework context and prevents duplicate registration.
*
* @param plugin plugin constructor to instantiate.
* @param config optional configuration for the plugin.
*/
addPlugin<P extends SigilPlugin>(plugin: SigilPluginConstructor<P>, config?: P extends SigilPlugin<infer C> ? C : undefined): void;
/**
* Mounts an existing Route instance at a given path.
* Connects it to framework internals and returns the route.
*
* @param path base path for mounting the route (e.g., "/api").
* @param route route instance to mount.
* @returns mounted Route instance.
*/
mount(path: string, route: Route<any>): Route<any>;
/**
* Defines and mounts a new Route at the specified path.
* Applies framework debug settings to the route.
*
* @param path base path for the new route.
* @param options optional route configuration (modifiers, tags, debug).
* @returns newly created and mounted Route instance.
*/
route<MW extends readonly ModifierConstructor<any, any>[] = any>(path: string, options?: RouteOptions<MW>): Route<MW, undefined, Record<string, string | undefined>, Record<string, string | undefined>>;
/**
* Starts the HTTP server listening on the specified port and host.
* Returns connection details and URL upon success.
*
* @param port TCP port number to listen on.
* @param host hostname or IP address to bind (default "localhost").
* @returns promise resolving to host, port, and URL of the server.
*/
listen(port: number, host?: string): Promise<{
host: string;
port: number;
url: URL;
}>;
}