refactor(errors): replace generic Error with Deno.errors types

- Change BasicAuth.create() to throw Deno.errors.InvalidData for empty users
- Change Context.ensureBodyNotConsumed() to throw Deno.errors.BadResource
- Change Context.render() and streamRender() to throw Deno.errors.NotSupported
- Change Engine.resolveTemplate() to throw Deno.errors.NotFound for missing templates
- Change Scanner.validateModule() to throw Deno.errors.InvalidData and TypeError
- Change Session.create() to throw Deno.errors.InvalidData for empty cookieSecret
- Remove trailing periods from single-line property JSDoc comments
- Update @throws tags to match actual error classes

Author: NeaByteLab

src/core/Context.ts

@@ -6,27 +6,27 @@ import * as Core from '@core/index.ts'
  * @description Parses body once; exposes headers, cookies, state.
  */
 export class Context {
-  /** Parsed body; undefined until parsed. */
+  /** Parsed body; undefined until parsed */
   private bodyData: unknown = undefined
-  /** Format body was parsed as. */
+  /** Format body was parsed as */
   private bodyParsedAs: 'arraybuffer' | 'blob' | 'form' | 'json' | 'text' | null = null
-  /** Parsed cookie name-to-value map; lazy. */
+  /** Parsed cookie name-to-value map; lazy */
   private cookieMap: Record<string, string> | undefined = undefined
-  /** Custom error handler when set. */
+  /** Custom error handler when set */
   private errorHandler: Types.ErrorHandler | undefined = undefined
-  /** Lowercased request header map; lazy. */
+  /** Lowercased request header map; lazy */
   private headerMap: Record<string, string> | undefined = undefined
-  /** Parsed query string params; lazy. */
+  /** Parsed query string params; lazy */
   private queryParams: Record<string, string> | undefined = undefined
-  /** Incoming fetch Request. */
+  /** Incoming fetch Request */
   private req: Request
-  /** Arbitrary state for middleware/handlers. */
+  /** Arbitrary state for middleware/handlers */
   private requestState: Record<string, unknown> = {}
-  /** Response headers to send. */
+  /** Response headers to send */
   private responseHeaders: Record<string, string> = {}
-  /** Matched route path params. */
+  /** Matched route path params */
   private routeParams: Record<string, string>
-  /** Parsed request URL. */
+  /** Parsed request URL */
   private urlObj: URL
 
   /**
@@ -285,7 +285,9 @@ export class Context {
   async render(templatePath: string, data: Types.TemplateData = {}): Promise<Response> {
     const view = this.state['view'] as Types.ViewEngine | undefined
     if (view === undefined) {
-      throw new Error('View engine not configured, set viewsDir in RouterOptions')
+      throw new Deno.errors.NotSupported(
+        'View engine not configured, set viewsDir in RouterOptions'
+      )
     }
     const html = await view.render(templatePath, data)
     return this.send.html(html)
@@ -344,7 +346,9 @@ export class Context {
   streamRender(templatePath: string, data: Types.TemplateData = {}): Response {
     const view = this.state['view'] as Types.ViewEngine
     if (view === undefined) {
-      throw new Error('View engine not configured, set viewsDir in RouterOptions')
+      throw new Deno.errors.NotSupported(
+        'View engine not configured, set viewsDir in RouterOptions'
+      )
     }
     const stream = view.streamRender(templatePath, data)
     return this.send.stream(stream, undefined, 'text/html; charset=utf-8')
@@ -365,14 +369,14 @@ export class Context {
     return this.bodyData as string
   }
 
-  /** Throws if body was already consumed. */
+  /** Throws if body was already consumed */
   private ensureBodyNotConsumed(): void {
     if (this.bodyParsedAs !== null) {
-      throw new Error('Request body already consumed')
+      throw new Deno.errors.BadResource('Request body already consumed')
     }
   }
 
-  /** Parse Cookie header into key-value map. */
+  /** Parse Cookie header into key-value map */
   private parseCookies(): void {
     const result: Record<string, string> = {}
     const cookieHeader = this.req.headers.get('cookie')
@@ -387,14 +391,14 @@ export class Context {
     this.cookieMap = result
   }
 
-  /** Parse request headers into lowercased map. */
+  /** Parse request headers into lowercased map */
   private parseHeaders(): void {
     this.headerMap = Object.fromEntries(
       Array.from(this.req.headers.entries(), ([key, value]) => [key.toLowerCase(), value])
     )
   }
 
-  /** Parse URL search params into map. */
+  /** Parse URL search params into map */
   private parseQuery(): void {
     this.queryParams = Object.fromEntries(this.urlObj.searchParams.entries())
   }

src/middleware/BasicAuth.ts

@@ -11,12 +11,12 @@ export class BasicAuth {
    * @description Validates Authorization header against user list.
    * @param options - List of username/password pairs
    * @returns Middleware that returns 401 when invalid
-   * @throws {Error} When users array is empty
+   * @throws {Deno.errors.InvalidData} When users array is empty
    */
   static create(options: Types.BasicAuthOptions): Types.Middleware {
     const { users } = options
     if (!users || users.length === 0) {
-      throw new Error('BasicAuth requires at least one user in the users array')
+      throw new Deno.errors.InvalidData('BasicAuth requires at least one user in the users array')
     }
     return async (
       ctx: Core.Context,

src/middleware/Session.ts

@@ -20,12 +20,12 @@ export class Session {
    * @description Populates ctx.state with session and helpers; requires cookieSecret.
    * @param options - Session options with required cookieSecret
    * @returns Middleware that populates ctx.state.session
-   * @throws {Error} When cookieSecret is missing or empty
+   * @throws {Deno.errors.InvalidData} When cookieSecret is missing or empty
    */
   static create(options: Types.SessionOptions): Types.Middleware {
     const { cookieSecret, ...rest } = options
     if (!cookieSecret || cookieSecret.length === 0) {
-      throw new Error('Session cookieSecret must be a non-empty string')
+      throw new Deno.errors.InvalidData('Session cookieSecret must be a non-empty string')
     }
     const sessionOptions = { ...Session.defaultOptions, ...rest } as Types.SessionCookieOpts
     return async (

src/rendering/Engine.ts

@@ -3,8 +3,8 @@ import * as Rendering from '@rendering/index.ts'
 import * as EngineParts from '@rendering/engine/index.ts'
 
 /**
- * Template rendering engine
- * @description Compiles and renders DVE templates with cache
+ * Template rendering engine.
+ * @description Compiles and renders DVE templates with cache.
  */
 export class Engine implements Types.ViewEngine {
   /** Default views directory */
@@ -17,8 +17,8 @@ export class Engine implements Types.ViewEngine {
   private discoveredPaths: Set<string> | null = null
 
   /**
-   * Create new engine instance
-   * @description Stores default viewsDir from options
+   * Create new engine instance.
+   * @description Stores default viewsDir from options.
    * @param options - Engine configuration options
    */
   constructor(options: Types.EngineOptions) {
@@ -40,18 +40,17 @@ export class Engine implements Types.ViewEngine {
     this.compileCache.delete(absPath)
   }
 
-  /** Reset discovered template paths */
-  refreshPaths(): void {
+  /** Reset discovered template paths */ refreshPaths(): void {
     this.discoveredPaths = null
   }
 
   /**
-   * Render template with data
-   * @description Loads template and produces final HTML
+   * Render template with data.
+   * @description Loads template and produces final HTML.
    * @param templatePath - Relative template path
    * @param data - Template scope data
    * @returns Rendered HTML string
-   * @throws {Error} When template path not discovered
+   * @throws {Deno.errors.NotFound} When template path not discovered
    */
   async render(templatePath: string, data: Types.TemplateData = {}): Promise<string> {
     const compiled = await this.resolveTemplate(templatePath)
@@ -64,7 +63,7 @@ export class Engine implements Types.ViewEngine {
    * @param templatePath - Relative template path
    * @param data - Template scope data
    * @returns ReadableStream with HTML content
-   * @throws {Error} When template not found
+   * @throws {Deno.errors.NotFound} When template not found
    */
   streamRender(templatePath: string, data: Types.TemplateData = {}): ReadableStream {
     const { readable, writable } = new TransformStream()
@@ -75,8 +74,8 @@ export class Engine implements Types.ViewEngine {
   }
 
   /**
-   * Compile template and cache
-   * @description Parses template text into AST nodes
+   * Compile template and cache.
+   * @description Parses template text into AST nodes.
    * @param absTemplatePath - Absolute path to template
    * @returns Compile result with AST
    */
@@ -93,8 +92,8 @@ export class Engine implements Types.ViewEngine {
   }
 
   /**
-   * Load template text with cache
-   * @description Loads file contents from disk once
+   * Load template text with cache.
+   * @description Loads file contents from disk once.
    * @param absPath - Absolute template file path
    * @returns Template file contents
    */
@@ -109,8 +108,8 @@ export class Engine implements Types.ViewEngine {
   }
 
   /**
-   * Render node to chunk
-   * @description Renders individual node to HTML chunk
+   * Render node to chunk.
+   * @description Renders individual node to HTML chunk.
    * @param node - AST node to render
    * @param data - Template scope data
    * @param viewsDir - Root directory for includes
@@ -164,8 +163,8 @@ export class Engine implements Types.ViewEngine {
   }
 
   /**
-   * Render AST nodes to HTML
-   * @description Evaluates variables, includes, and blocks
+   * Render AST nodes to HTML.
+   * @description Evaluates variables, includes, and blocks.
    * @param ast - Parsed template AST nodes
    * @param data - Current scope data
    * @param viewsDir - Root directory for includes
@@ -187,8 +186,8 @@ export class Engine implements Types.ViewEngine {
   }
 
   /**
-   * Render template nodes to stream
-   * @description Streams HTML output progressively
+   * Render template nodes to stream.
+   * @description Streams HTML output progressively.
    * @param templatePath - Relative template path
    * @param data - Template scope data
    * @param writable - Writable stream for output
@@ -218,7 +217,7 @@ export class Engine implements Types.ViewEngine {
    * @description Discovers paths, normalizes, validates, and compiles.
    * @param templatePath - Relative template path
    * @returns Compiled template with AST
-   * @throws {Error} When template not found
+   * @throws {Deno.errors.NotFound} When template not found
    */
   private async resolveTemplate(templatePath: string): Promise<Types.CompileResult> {
     if (this.discoveredPaths === null) {
@@ -229,7 +228,7 @@ export class Engine implements Types.ViewEngine {
       ? normalizedPath
       : `${normalizedPath}.dve`
     if (!this.discoveredPaths.has(pathWithExt)) {
-      throw new Error(`Template "${templatePath}" not found in views directory`)
+      throw new Deno.errors.NotFound(`Template "${templatePath}" not found in views directory`)
     }
     const absPath = EngineParts.Utils.join(this.defaultViewsDir, pathWithExt)
     return await this.compileTemplate(absPath)

src/routing/Scanner.ts

@@ -117,7 +117,7 @@ export class Scanner {
    * @param module - Loaded route module object
    * @param routePath - Path for error messages
    * @param methods - Valid HTTP method names
-   * @throws {Error} When no method or non-function export
+   * @throws {Deno.errors.InvalidData} When no method or non-function export
    */
   static validateModule(
     module: Record<string, unknown>,
@@ -126,14 +126,14 @@ export class Scanner {
   ): void {
     const exportedMethods = Object.keys(module).filter((key) => methods.includes(key))
     if (exportedMethods.length === 0) {
-      throw new Error(
+      throw new Deno.errors.InvalidData(
         `Route "${routePath}" must export at least one HTTP method (${methods.join(', ')})`
       )
     }
     for (const [key, value] of Object.entries(module)) {
       if (methods.includes(key)) {
         if (typeof value !== 'function') {
-          throw new Error(
+          throw new TypeError(
             `Route "${routePath}" export "${key}" must be a function, got ${typeof value}`
           )
         }