yinzerflow 0.2.0 → 0.2.2

package/YinzerFlow.d.ts

@@ -1,13 +1,17 @@
-type CreateEnum<T> = T[keyof T];
-type DeepPartial<T> = {
+export type CreateEnum<T> = T[keyof T];
+/**
+ * Utility type for deep partial - makes all properties optional recursively
+ * Used internally to create public configuration types from internal shapes
+ */
+export type DeepPartial<T> = {
 	[P in keyof T]?: T[P] extends object ? T[P] extends Array<infer U> ? Array<U> // Keep arrays as-is, don't make array items partial
 	 : DeepPartial<T[P]> : T[P];
 };
-interface InternalHandlerCallbackGenerics {
-	body: unknown;
-	response: unknown;
-	query: Record<string, string>;
-	params: Record<string, string>;
+export interface InternalHandlerCallbackGenerics {
+	body?: unknown;
+	response?: unknown;
+	query?: Record<string, string>;
+	params?: Record<string, string>;
 }
 declare const httpStatusCode: {
 	readonly ok: 200;
@@ -122,10 +126,10 @@ declare const httpHeaders: {
 	readonly clearSiteData: "Clear-Site-Data";
 	readonly noVarySearch: "No-Vary-Search";
 };
-type InternalHttpStatusCode = CreateEnum<typeof httpStatusCode>;
-type InternalHttpMethod = CreateEnum<typeof httpMethod>;
-type InternalHttpHeaders = Lowercase<CreateEnum<typeof httpHeaders>> | string;
-interface Request$1<T = InternalHandlerCallbackGenerics> {
+export type InternalHttpStatusCode = CreateEnum<typeof httpStatusCode>;
+export type InternalHttpMethod = CreateEnum<typeof httpMethod>;
+export type InternalHttpHeaders = Lowercase<CreateEnum<typeof httpHeaders>> | string;
+interface Request$1<T extends InternalHandlerCallbackGenerics = InternalHandlerCallbackGenerics> {
 	protocol: string;
 	method: InternalHttpMethod;
 	path: string;
@@ -141,17 +145,27 @@ interface Response$1 {
 	addHeaders: (headers: Partial<Record<InternalHttpHeaders, string>>) => void;
 	removeHeaders: (headerNames: Array<InternalHttpHeaders>) => void;
 }
-interface Context {
-	request: Request$1;
+export interface Context<T extends InternalHandlerCallbackGenerics = InternalHandlerCallbackGenerics> {
+	request: Request$1<T>;
 	response: Response$1;
 }
-type HandlerCallback<T = InternalHandlerCallbackGenerics> = (ctx: Context) => Promise<T["response"] | void> | T["response"] | void;
-type InternalGlobalHookOptions = {
+/**
+ * Represents a route handler function that returns a response body
+ *
+ * This type defines the signature for route handlers that process requests
+ * and return a response. The function can return either a promise that resolves
+ * to a response body or a response body directly.
+ *
+ * @param ctx - The request context containing request and response objects
+ * @returns A response body or a promise that resolves to a response body
+ */
+export type HandlerCallback<T extends InternalHandlerCallbackGenerics = InternalHandlerCallbackGenerics> = (ctx: Context<T>) => Promise<T["response"] | void> | T["response"] | void;
+export type InternalGlobalHookOptions = {
 	routesToExclude: Array<string>;
 } & {
 	routesToInclude: Array<string>;
 };
-interface InternalHookRegistryImpl {
+export interface InternalHookRegistryImpl {
 	readonly _beforeAll: Set<{
 		handler: HandlerCallback;
 		options?: InternalGlobalHookOptions;
@@ -167,17 +181,17 @@ interface InternalHookRegistryImpl {
 	_addOnError: (handler: HandlerCallback) => void;
 	_addOnNotFound: (handler: HandlerCallback) => void;
 }
-interface InternalRouteRegistryImpl {
+export interface InternalRouteRegistryImpl {
 	readonly _exactRoutes: Map<InternalHttpMethod, Map<string, InternalRouteRegistry>>;
 	readonly _parameterizedRoutes: Map<InternalHttpMethod, Array<InternalPreCompiledRoute>>;
 	_register: (route: InternalRouteRegistry) => void;
 	_findRoute: (method: InternalHttpMethod, path: string) => InternalRouteRegistry | undefined;
 }
-interface InternalRouteRegistryOptions {
+export interface InternalRouteRegistryOptions {
 	beforeHooks: Array<HandlerCallback>;
 	afterHooks: Array<HandlerCallback>;
 }
-interface InternalRouteRegistry {
+export interface InternalRouteRegistry {
 	prefix?: string;
 	path: string;
 	method: InternalHttpMethod;
@@ -185,24 +199,55 @@ interface InternalRouteRegistry {
 	options: InternalRouteRegistryOptions;
 	params: Record<string, string>;
 }
-interface InternalPreCompiledRoute extends InternalRouteRegistry {
+/**
+ * Pre-compiled route with regex pattern for efficient runtime matching
+ *
+ * We compile route patterns into regexes at registration time (server startup)
+ * rather than at request time for performance reasons:
+ * - Registration: O(1) one-time cost per route
+ * - Runtime: O(1) for exact routes, O(n) for parameterized routes with pre-compiled regex
+ *
+ * Example: "/users/:id/posts/:postId" becomes:
+ * - pattern: /^\/users\/([^\/]+)\/posts\/([^\/]+)$/
+ * - paramNames: ["id", "postId"]
+ */
+export interface InternalPreCompiledRoute extends InternalRouteRegistry {
 	pattern: RegExp;
 	paramNames: Array<string>;
 	isParameterized: boolean;
 }
 declare const logLevels: {
 	readonly off: "off";
-	readonly verbose: "verbose";
-	readonly network: "network";
+	readonly error: "error";
+	readonly warn: "warn";
+	readonly info: "info";
 };
-type InternalCorsConfiguration = InternalCorsDisabledConfiguration | InternalCorsEnabledConfiguration;
-interface InternalCorsDisabledConfiguration {
+export interface Logger {
+	info: (...args: Array<unknown>) => void;
+	warn: (...args: Array<unknown>) => void;
+	error: (...args: Array<unknown>) => void;
+	debug?: (...args: Array<unknown>) => void;
+	trace?: (...args: Array<unknown>) => void;
+}
+/**
+ * Internal CORS Configuration Options
+ * Provides fine-grained control over Cross-Origin Resource Sharing
+ */
+export type InternalCorsConfiguration = InternalCorsDisabledConfiguration | InternalCorsEnabledConfiguration;
+/**
+ * Internal CORS Disabled Configuration
+ */
+export interface InternalCorsDisabledConfiguration {
 	/**
 	 * Disable CORS handling
 	 */
 	enabled: false;
 }
-interface InternalCorsEnabledConfiguration {
+/**
+ * Internal CORS Enabled Configuration
+ * When CORS is enabled, origin is required
+ */
+export interface InternalCorsEnabledConfiguration {
 	/**
 	 * Enable CORS handling
 	 */
@@ -221,15 +266,21 @@ interface InternalCorsEnabledConfiguration {
 	 */
 	methods: Array<string>;
 	/**
-	 * Headers allowed in CORS requests
-	 * - string[]: Specific headers
-	 * - '*': Allow all headers
+	 * Headers allowed in CORS requests   *
 	 * @default ['*']
+	 *
+	 * These are the headers that will be allowed in each request.
+	 * These headers typically include things like 'Content-Type', 'Authorization', 'X-Requested-With', etc.
+	 * Other common headers would include headers needed for third party services like stripe or AWS via webhooks.
 	 */
 	allowedHeaders: Array<string> | string | "*";
 	/**
 	 * Headers exposed to the client in CORS responses
 	 * @default []
+	 *
+	 * These are headers that in simple terms give the client "Permission" to access the headers in the response.
+	 * For more context, the response can send as many headers as it wants, but the client can only access the headers that are exposed
+	 * in this array.
 	 */
 	exposedHeaders: Array<string>;
 	/**
@@ -257,7 +308,10 @@ interface InternalCorsEnabledConfiguration {
 	 */
 	optionsSuccessStatus: InternalHttpStatusCode;
 }
-interface InternalConnectionOptions {
+/**
+ * Internal Connection Options
+ */
+export interface InternalConnectionOptions {
 	/**
 	 * Default socket timeout in milliseconds (30 seconds)
 	 *
@@ -293,7 +347,11 @@ interface InternalConnectionOptions {
 	 */
 	headersTimeout: number;
 }
-interface InternalBodyParserConfiguration {
+/**
+ * Internal Body Parser Security Configuration
+ * Protects against DoS attacks, prototype pollution, and memory exhaustion
+ */
+export interface InternalBodyParserConfiguration {
 	/**
 	 * JSON parsing security configuration
 	 */
@@ -307,7 +365,11 @@ interface InternalBodyParserConfiguration {
 	 */
 	urlEncoded: InternalUrlEncodedConfiguration;
 }
-interface InternalJsonParserConfiguration {
+/**
+ * Internal JSON Parser Security Configuration
+ * Protects against JSON-specific attacks like prototype pollution and DoS
+ */
+export interface InternalJsonParserConfiguration {
 	/**
 	 * Maximum JSON request body size in bytes
 	 * @default 262144 (256KB) - reasonable for API payloads
@@ -345,7 +407,10 @@ interface InternalJsonParserConfiguration {
 	 */
 	maxArrayLength: number;
 }
-interface InternalFileUploadConfiguration {
+/**
+ * Internal File Upload Security Configuration
+ */
+export interface InternalFileUploadConfiguration {
 	/**
 	 * Maximum size per file in bytes
 	 * @default 10485760 (10MB) - reasonable for documents/images
@@ -382,7 +447,10 @@ interface InternalFileUploadConfiguration {
 	 */
 	maxFilenameLength: number;
 }
-interface InternalUrlEncodedConfiguration {
+/**
+ * Internal URL-encoded Configuration
+ */
+export interface InternalUrlEncodedConfiguration {
 	/**
 	 * Maximum URL-encoded form data size in bytes
 	 * @default 1048576 (1MB)
@@ -408,7 +476,10 @@ interface InternalUrlEncodedConfiguration {
 	 */
 	maxFieldLength: number;
 }
-interface InternalIpValidationConfig {
+/**
+ * Internal IP Security Configuration
+ */
+export interface InternalIpValidationConfig {
 	/**
 	 * List of trusted proxy IP addresses that are allowed to set forwarded headers
 	 * Only these IPs can provide X-Forwarded-For and similar headers
@@ -445,7 +516,12 @@ interface InternalIpValidationConfig {
 	 */
 	detectSpoofing: boolean;
 }
-interface InternalServerConfiguration {
+/**
+ * Complete internal server configuration shape - single source of truth
+ * This defines ALL possible configuration options with their required types
+ * Used as the foundation for both internal (complete) and public (partial) configurations
+ */
+export interface InternalServerConfiguration {
 	/**
 	 * Port number for the server to listen on
 	 * @default 5000
@@ -457,13 +533,35 @@ interface InternalServerConfiguration {
 	 */
 	host: string;
 	/**
-	 * Logging level for YinzerFlow server
-	 * - 'off': No logging (silent mode)
-	 * - 'verbose': Application logging with Pittsburgh personality (level 1)
-	 * - 'network': Network logging + application logging (level 2)
-	 * @default 'off'
+	 * Application logging level for YinzerFlow server
+	 * - 'off': No application logging (silent mode)
+	 * - 'error': Only error messages
+	 * - 'warn': Warning and error messages
+	 * - 'info': All application logging with Pittsburgh personality
+	 * @default 'warn'
 	 */
 	logLevel: CreateEnum<typeof logLevels>;
+	/**
+	 * Custom logger implementation
+	 * If provided, this logger will be used instead of the built-in YinzerFlow logger
+	 * Must implement the Logger interface
+	 * @default undefined (uses built-in logger)
+	 */
+	logger?: Logger;
+	/**
+	 * Network request/response logging (nginx-style logs)
+	 * Completely separate from application logs - simple on/off toggle
+	 * @default false
+	 */
+	networkLogs: boolean;
+	/**
+	 * Custom logger for network logs (optional)
+	 * If provided, network logs will be routed to this logger instead of built-in formatting
+	 * Can be the same as the application logger or a different one
+	 * Useful for unified monitoring (e.g., Winston with Datadog transport for both app and network logs)
+	 * @default undefined (uses built-in network logging)
+	 */
+	networkLogger?: Logger;
 	/**
 	 * Cross-Origin Resource Sharing configuration
 	 */
@@ -481,7 +579,7 @@ interface InternalServerConfiguration {
 	 */
 	connectionOptions: InternalConnectionOptions;
 }
-interface Setup {
+export interface Setup {
 	get: InternalSetupMethod;
 	post: InternalSetupMethod;
 	put: InternalSetupMethod;
@@ -494,8 +592,8 @@ interface Setup {
 	onError: (handler: HandlerCallback) => void;
 	onNotFound: (handler: HandlerCallback) => void;
 }
-type InternalSetupMethod = (path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions) => void;
-interface InternalSetupImpl extends Setup {
+export type InternalSetupMethod = (path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions) => void;
+export interface InternalSetupImpl extends Setup {
 	readonly _configuration: InternalServerConfiguration;
 	readonly _routeRegistry: InternalRouteRegistryImpl;
 	readonly _hooks: InternalHookRegistryImpl;
@@ -517,7 +615,13 @@ declare class HookRegistryImpl implements InternalHookRegistryImpl {
 	_addOnError(handler: HandlerCallback): void;
 	_addOnNotFound(handler: HandlerCallback): void;
 }
-type ServerConfiguration = DeepPartial<InternalServerConfiguration>;
+/**
+ * User-facing configuration interface where all properties are optional
+ * Users only need to specify what they want to override from defaults
+ *
+ * This is created by making the complete internal ServerConfigurationShape partially optional
+ */
+export type ServerConfiguration = DeepPartial<InternalServerConfiguration>;
 declare class RouteRegistryImpl implements InternalRouteRegistryImpl {
 	readonly _exactRoutes: Map<InternalHttpMethod, Map<string, InternalRouteRegistry>>;
 	readonly _parameterizedRoutes: Map<InternalHttpMethod, InternalPreCompiledRoute[]>;