vector-framework 0.8.1

package/src/types/index.ts

@@ -0,0 +1,126 @@
+import type { IRequest } from 'itty-router';
+
+// Default AuthUser type - users can override this with their own type
+export interface DefaultAuthUser {
+  id: string;
+  email?: string;
+  role?: string;
+  permissions?: string[];
+  [key: string]: any;
+}
+
+// Extensible type configuration interface
+// Users can override any of these types without breaking changes
+export interface VectorTypes {
+  auth?: any; // Custom auth user type
+  context?: any; // Custom request context (future)
+  cache?: any; // Custom cache value type (future)
+  metadata?: any; // Custom metadata type (future)
+}
+
+// Default types
+export interface DefaultVectorTypes extends VectorTypes {
+  auth: DefaultAuthUser;
+  context: Record<string, any>;
+  cache: any;
+  metadata: Record<string, any>;
+}
+
+// Type helpers
+export type GetAuthType<T extends VectorTypes> = T['auth'] extends undefined
+  ? DefaultAuthUser
+  : T['auth'];
+
+export type GetContextType<T extends VectorTypes> = T['context'] extends undefined
+  ? Record<string, any>
+  : T['context'];
+
+export type GetCacheType<T extends VectorTypes> = T['cache'] extends undefined ? any : T['cache'];
+
+export type GetMetadataType<T extends VectorTypes> = T['metadata'] extends undefined
+  ? Record<string, any>
+  : T['metadata'];
+
+// Legacy support - keep AuthUser for backward compatibility
+export type AuthUser = DefaultAuthUser;
+
+export interface VectorRequest<TTypes extends VectorTypes = DefaultVectorTypes>
+  extends Omit<IRequest, 'params'> {
+  authUser?: GetAuthType<TTypes>;
+  context: GetContextType<TTypes>;
+  metadata?: GetMetadataType<TTypes>;
+  content?: any;
+  params?: Record<string, string>;
+  startTime?: number;
+  [key: string]: any;
+}
+
+export interface CacheOptions {
+  key?: string;
+  ttl?: number;
+}
+
+export interface RouteOptions<TTypes extends VectorTypes = DefaultVectorTypes> {
+  method: string;
+  path: string;
+  auth?: boolean;
+  expose?: boolean;
+  cache?: CacheOptions | number;
+  rawRequest?: boolean;
+  rawResponse?: boolean;
+  responseContentType?: string;
+  metadata?: GetMetadataType<TTypes>;
+}
+
+export interface VectorConfig<TTypes extends VectorTypes = DefaultVectorTypes> {
+  port?: number;
+  hostname?: string;
+  reusePort?: boolean;
+  development?: boolean;
+  cors?: CorsOptions;
+  before?: BeforeMiddlewareHandler<TTypes>[];
+  finally?: AfterMiddlewareHandler<TTypes>[];
+  routesDir?: string;
+  autoDiscover?: boolean;
+}
+
+export interface CorsOptions {
+  origin?: string | string[] | ((origin: string) => boolean);
+  credentials?: boolean;
+  allowHeaders?: string | string[];
+  allowMethods?: string | string[];
+  exposeHeaders?: string | string[];
+  maxAge?: number;
+}
+
+export type BeforeMiddlewareHandler<TTypes extends VectorTypes = DefaultVectorTypes> = (
+  request: VectorRequest<TTypes>
+) => Promise<VectorRequest<TTypes> | Response> | VectorRequest<TTypes> | Response;
+
+export type AfterMiddlewareHandler<TTypes extends VectorTypes = DefaultVectorTypes> = (
+  response: Response,
+  request: VectorRequest<TTypes>
+) => Promise<Response> | Response;
+export type MiddlewareHandler = BeforeMiddlewareHandler | AfterMiddlewareHandler;
+
+export type RouteHandler<TTypes extends VectorTypes = DefaultVectorTypes> = (
+  request: VectorRequest<TTypes>
+) => Promise<any> | any;
+
+export type ProtectedHandler<TTypes extends VectorTypes = DefaultVectorTypes> = (
+  request: VectorRequest<TTypes>
+) => Promise<GetAuthType<TTypes>> | GetAuthType<TTypes>;
+
+export type CacheHandler = (key: string, factory: () => Promise<any>, ttl: number) => Promise<any>;
+
+export interface RouteDefinition<TTypes extends VectorTypes = DefaultVectorTypes> {
+  options: RouteOptions<TTypes>;
+  handler: RouteHandler<TTypes>;
+}
+
+export interface GeneratedRoute<TTypes extends VectorTypes = DefaultVectorTypes> {
+  name: string;
+  path: string;
+  method: string;
+  options: RouteOptions<TTypes>;
+}

package/src/utils/logger.ts

@@ -0,0 +1,87 @@
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+}
+
+export interface LoggerConfig {
+  level: LogLevel;
+  prefix?: string;
+  timestamp?: boolean;
+}
+
+export class Logger {
+  private config: LoggerConfig;
+
+  constructor(config: Partial<LoggerConfig> = {}) {
+    this.config = {
+      level: config.level ?? LogLevel.INFO,
+      prefix: config.prefix ?? '[Vector]',
+      timestamp: config.timestamp ?? true,
+    };
+  }
+
+  private formatMessage(level: string, message: string): string {
+    const parts: string[] = [];
+
+    if (this.config.timestamp) {
+      parts.push(`[${new Date().toISOString()}]`);
+    }
+
+    if (this.config.prefix) {
+      parts.push(this.config.prefix);
+    }
+
+    parts.push(`[${level}]`);
+    parts.push(message);
+
+    return parts.join(' ');
+  }
+
+  debug(message: string, ...args: any[]): void {
+    if (this.config.level <= LogLevel.DEBUG) {
+      console.log(this.formatMessage('DEBUG', message), ...args);
+    }
+  }
+
+  info(message: string, ...args: any[]): void {
+    if (this.config.level <= LogLevel.INFO) {
+      console.log(this.formatMessage('INFO', message), ...args);
+    }
+  }
+
+  warn(message: string, ...args: any[]): void {
+    if (this.config.level <= LogLevel.WARN) {
+      console.warn(this.formatMessage('WARN', message), ...args);
+    }
+  }
+
+  error(message: string, error?: Error): void {
+    if (this.config.level <= LogLevel.ERROR) {
+      console.error(this.formatMessage('ERROR', message));
+      if (error) {
+        console.error(error.stack || error.message);
+      }
+    }
+  }
+
+  success(message: string): void {
+    console.log(`✅ ${message}`);
+  }
+
+  loading(message: string): void {
+    console.log(`⏳ ${message}`);
+  }
+
+  setLevel(level: LogLevel): void {
+    this.config.level = level;
+  }
+}
+
+export const logger = new Logger({
+  level: process.env.LOG_LEVEL
+    ? (LogLevel[process.env.LOG_LEVEL as keyof typeof LogLevel] ?? LogLevel.INFO)
+    : LogLevel.INFO,
+  timestamp: process.env.NODE_ENV !== 'production',
+});

package/src/utils/validation.ts

@@ -0,0 +1,58 @@
+import { DEFAULT_CONFIG } from '../constants';
+import type { CorsOptions, VectorConfig } from '../types';
+
+export function validateConfig(config: VectorConfig): VectorConfig {
+  const validatedConfig: VectorConfig = {
+    port: validatePort(config.port),
+    hostname: config.hostname || DEFAULT_CONFIG.HOSTNAME,
+    reusePort: config.reusePort !== false,
+    development: config.development || false,
+    routesDir: config.routesDir || DEFAULT_CONFIG.ROUTES_DIR,
+    autoDiscover: config.autoDiscover !== false,
+    cors: config.cors ? validateCorsOptions(config.cors) : undefined,
+    before: config.before || [],
+    finally: config.finally || [],
+  };
+
+  return validatedConfig;
+}
+
+function validatePort(port?: number): number {
+  if (port === undefined) {
+    return DEFAULT_CONFIG.PORT;
+  }
+
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid port: ${port}. Port must be between 1 and 65535.`);
+  }
+
+  return port;
+}
+
+function validateCorsOptions(cors: CorsOptions | boolean): CorsOptions | undefined {
+  if (cors === false) {
+    return undefined;
+  }
+
+  if (cors === true) {
+    return {
+      origin: '*',
+      credentials: true,
+      allowHeaders: ['Content-Type', 'Authorization'],
+      allowMethods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+      exposeHeaders: ['Authorization'],
+      maxAge: DEFAULT_CONFIG.CORS_MAX_AGE,
+    };
+  }
+
+  return cors;
+}
+
+export function isValidHttpMethod(method: string): boolean {
+  const validMethods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD'];
+  return validMethods.includes(method.toUpperCase());
+}
+
+export function isValidPath(path: string): boolean {
+  return path.startsWith('/') && !path.includes(' ');
+}