Merge pull request #155 from supercharge/view-builder-refinements

View builder refinements

CHANGELOG.md

@@ -10,6 +10,7 @@
 - `@supercharge/contracts`
     - allow users to define only selected hashing driver constructros in `HashConfig#drivers`
     - export a `ViteConfig` interface
+    - extend `ViewConfigBuilder` interface: add `withoutLayout` method
     - export `RenderableError` and `ReportableError` interfaces
         - `RenderableError` defines the `render(error, httpContext)` method
         - `ReportableError` defines the `report(error, httpContext)` method
@@ -26,10 +27,15 @@
 - bump dependencies
 - `@supercharge/vite`
     - add Vite `^5.0.0` as a peer dependency
+- `@supercharge/view`
+    - implement `withoutLayout` method on `ViewConfigBuilder` instance
+    - rename view `engines` folder to `drivers`
 
 ### Breaking Changes
 - `@supercharge/vite`
     - require Vite `>=4.0.0` as a peer dependency
+- `@supercharge/view`
+    - rename `HandlebarsCompiler` to `HandlebarsDriver`
 
 
 ## [4.0.0-alpha.1](https://github.com/supercharge/framework/compare/v4.0.0-alpha.0...v4.0.0-alpha.1) - 2023-11-18

packages/contracts/src/view/config-builder.ts

@@ -5,4 +5,9 @@ export interface ViewConfigBuilder {
    * the file name of the layout file in the configured layouts folder.
    */
   layout(name: string): this
+
+  /**
+   * Render this view without a base layout.
+   */
+  withoutLayout(): this
 }

packages/view/src/engines/handlebars/base-compiler.ts → packages/view/src/drivers/base-driver.ts

@@ -1,7 +1,7 @@
 
 import { ViewSharedData } from '@supercharge/contracts'
 
-export class ViewBaseCompiler {
+export class ViewBaseDriver {
   /**
    * Stores the data that is available to all view templates.
    */

packages/view/src/engines/handlebars/compiler.ts → packages/view/src/drivers/handlebars/handlebars-driver.ts

@@ -4,15 +4,19 @@ import Fs from '@supercharge/fs'
 import { fileURLToPath } from 'node:url'
 import { Str } from '@supercharge/strings'
 import { Collect } from '@supercharge/collections'
-import { ViewBaseCompiler } from './base-compiler.js'
+import { ViewBaseDriver } from '../base-driver.js'
 import Handlebars, { HelperDelegate } from 'handlebars'
 import { resolveDefaultImport, tap } from '@supercharge/goodies'
 import { Logger, ViewConfig, ViewEngine, ViewResponseConfig } from '@supercharge/contracts'
 
+interface ReadTemplateConfig {
+  isLayout?: boolean
+}
+
 // eslint-disable-next-line @typescript-eslint/naming-convention
 const __dirname = Path.dirname(fileURLToPath(import.meta.url))
 
-export class HandlebarsCompiler extends ViewBaseCompiler implements ViewEngine {
+export class HandlebarsDriver extends ViewBaseDriver implements ViewEngine {
   /**
      * The handlebars renderer instance.
      */
@@ -55,7 +59,7 @@ export class HandlebarsCompiler extends ViewBaseCompiler implements ViewEngine {
       return layoutLocation
     }
 
-    throw new Error(`Path to view layouts not existing. Received ${layoutLocation}`)
+    throw new Error(`Path to view layouts not existing. Received "${layoutLocation}"`)
   }
 
   /**
@@ -75,7 +79,7 @@ export class HandlebarsCompiler extends ViewBaseCompiler implements ViewEngine {
       return viewsLocation
     }
 
-    throw new Error(`Path to view files not existing. Received ${viewsLocation}`)
+    throw new Error(`Path to view files not existing. Received "${viewsLocation}"`)
   }
 
   /**
@@ -322,7 +326,7 @@ export class HandlebarsCompiler extends ViewBaseCompiler implements ViewEngine {
     const file = this.ensureExtension(view)
 
     if (await Fs.notExists(file)) {
-      throw new Error(`View file does not exist. Tried to load ${file}`)
+      throw new Error(`View file does not exist. Tried to load "${file}"`)
     }
   }
 
@@ -333,7 +337,3 @@ export class HandlebarsCompiler extends ViewBaseCompiler implements ViewEngine {
     return Str(template).finish(this.extension).get()
   }
 }
-
-interface ReadTemplateConfig {
-  isLayout?: boolean
-}

packages/view/src/drivers/handlebars/index.ts

@@ -0,0 +1,2 @@
+
+export * from './handlebars-driver.js'

packages/view/src/index.ts

@@ -1,5 +1,5 @@
 
-export { HandlebarsCompiler } from './engines/index.js'
+export { HandlebarsDriver } from './drivers/index.js'
 export { ViewConfigBuilder } from './view-config-builder.js'
 export { ViewManager } from './view-manager.js'
 export { ViewResponse } from './view-response.js'

packages/view/src/view-config-builder.ts

@@ -15,6 +15,13 @@ export class ViewConfigBuilder implements ViewConfigBuilderContract {
     this.config = config
   }
 
+  /**
+   * Create a new view config builder instance.
+   */
+  static from (config: ViewResponseConfig): ViewConfigBuilder {
+    return new this(config)
+  }
+
   /**
    * Set the base layout used to render this view. The given `name` identifies
    * the file name of the layout file in the configured layouts folder.
@@ -24,4 +31,11 @@ export class ViewConfigBuilder implements ViewConfigBuilderContract {
       this.config.layout = name
     })
   }
+
+  /**
+   * Render this view without a base layout.
+   */
+  withoutLayout (): this {
+    return this.layout('')
+  }
 }

packages/view/src/view-manager.ts

@@ -2,7 +2,7 @@
 import { tap } from '@supercharge/goodies'
 import { HelperDelegate } from 'handlebars'
 import { Manager } from '@supercharge/manager'
-import { HandlebarsCompiler } from './engines/handlebars/index.js'
+import { HandlebarsDriver } from './drivers/handlebars/index.js'
 import { Application, ViewConfig, ViewEngine, ViewResponseConfig, ViewSharedData } from '@supercharge/contracts'
 
 export class ViewManager extends Manager<Application> implements ViewEngine {
@@ -53,7 +53,7 @@ export class ViewManager extends Manager<Application> implements ViewEngine {
    * Create a Handlebars view renderer instance.
    */
   protected createHandlebarsDriver (): ViewEngine {
-    return new HandlebarsCompiler(this.app.logger(), this.meta.config.handlebars)
+    return new HandlebarsDriver(this.app.logger(), this.meta.config.handlebars)
   }
 
   /**

packages/view/src/view-response.ts

@@ -40,7 +40,7 @@ export class ViewResponse {
   /**
     * Assigns the rendered HTML of the given `template` as the response payload.
     */
-  private async renderView (template: string, data?: any, viewBuilder?: ViewBuilderCallback): Promise<string> {
+  private async renderView (template: string, data?: any, viewBuilderCallback?: ViewBuilderCallback): Promise<string> {
     const viewData = {
       ...this.response.state().all(),
       ...this.viewEngine.sharedData(),
@@ -49,9 +49,9 @@ export class ViewResponse {
 
     const viewConfig: ViewResponseConfig = {}
 
-    if (typeof viewBuilder === 'function') {
-      viewBuilder(
-        new ViewConfigBuilder(viewConfig)
+    if (typeof viewBuilderCallback === 'function') {
+      viewBuilderCallback(
+        ViewConfigBuilder.from(viewConfig)
       )
     }
 

packages/view/test/view-manager.js

@@ -53,7 +53,7 @@ test('throws for invalid views path', async () => {
 
   await expect(async () => {
     return view.render('test-view')
-  }).rejects.toThrow(`Path to view files not existing. Received ${viewsPath}`)
+  }).rejects.toThrow(`Path to view files not existing. Received "${viewsPath}"`)
 })
 
 test('throws when rendering a view with not-existing layout', async () => {
@@ -77,7 +77,7 @@ test('throws for misconfigured layouts path', async () => {
 
   await expect(async () => {
     await view.render('test-view', { name: 'Supercharge ' }, { layout: 'test' })
-  }).rejects.toThrow(`Path to view layouts not existing. Received ${layoutsPath}`)
+  }).rejects.toThrow(`Path to view layouts not existing. Received "${layoutsPath}"`)
 })
 
 test('throws when rendering a view with not-existing layout', async () => {