yinzerflow 0.2.0 → 0.2.1

package/YinzerFlow.d.ts

@@ -1,9 +1,13 @@
-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 {
+export interface InternalHandlerCallbackGenerics {
 	body: unknown;
 	response: unknown;
 	query: Record<string, string>;
@@ -122,9 +126,9 @@ 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;
+export type InternalHttpStatusCode = CreateEnum<typeof httpStatusCode>;
+export type InternalHttpMethod = CreateEnum<typeof httpMethod>;
+export type InternalHttpHeaders = Lowercase<CreateEnum<typeof httpHeaders>> | string;
 interface Request$1<T = InternalHandlerCallbackGenerics> {
 	protocol: string;
 	method: InternalHttpMethod;
@@ -141,17 +145,27 @@ interface Response$1 {
 	addHeaders: (headers: Partial<Record<InternalHttpHeaders, string>>) => void;
 	removeHeaders: (headerNames: Array<InternalHttpHeaders>) => void;
 }
-interface Context {
+export interface Context {
 	request: Request$1;
 	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 = InternalHandlerCallbackGenerics> = (ctx: Context) => 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,7 +199,19 @@ 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;
@@ -195,14 +221,25 @@ declare const logLevels: {
 	readonly verbose: "verbose";
 	readonly network: "network";
 };
-type InternalCorsConfiguration = InternalCorsDisabledConfiguration | InternalCorsEnabledConfiguration;
-interface InternalCorsDisabledConfiguration {
+/**
+ * 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
 	 */
@@ -257,7 +294,10 @@ interface InternalCorsEnabledConfiguration {
 	 */
 	optionsSuccessStatus: InternalHttpStatusCode;
 }
-interface InternalConnectionOptions {
+/**
+ * Internal Connection Options
+ */
+export interface InternalConnectionOptions {
 	/**
 	 * Default socket timeout in milliseconds (30 seconds)
 	 *
@@ -293,7 +333,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 +351,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 +393,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 +433,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 +462,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 +502,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
@@ -481,7 +543,7 @@ interface InternalServerConfiguration {
 	 */
 	connectionOptions: InternalConnectionOptions;
 }
-interface Setup {
+export interface Setup {
 	get: InternalSetupMethod;
 	post: InternalSetupMethod;
 	put: InternalSetupMethod;
@@ -494,8 +556,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 +579,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[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yinzerflow",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "author": "Patrick Rizzardi <patrick@redact.digital> (https://redact.digital)",
   "license": "MIT",
   "homepage": "https://github.com/yinzers/YinzerFlow.git",
@@ -22,8 +22,8 @@
     "bun",
     "yinzerflow"
   ],
-  "types": "lib/YinzerFlow.d.ts",
-  "main": "lib/YinzerFlow.js",
+  "types": "YinzerFlow.d.ts",
+  "main": "YinzerFlow.js",
   "type": "module",
   "scripts": {
     "test": "bun test --watch --coverage",