Skip to content

feat: support render function for json dirlist - #630

Open
helmipradita wants to merge 2 commits into
fastify:mainfrom
helmipradita:feat/dirlist-json-render
Open

helmipradita wants to merge 2 commits into
fastify:mainfrom
helmipradita:feat/dirlist-json-render

Conversation

@helmipradita

Copy link
Copy Markdown

Fixes #221

Checklist

Description

  • Allow directory listings in json format to use list.render to customize the output response.
  • Pass the selected format ('html' | 'json') to the list.render function so consumers can handle both or differentiate when query parameters (?format=...) override default options.
  • Update docs, TypeScript typings (ListJsonRender), and unit test suite with 100% coverage.

@SameRainbows

Copy link
Copy Markdown

Tested and verified against the directory listing test suite.

Key points verified:

  • Previously, list.render was only used for HTML mode, leaving JSON directory listings restricted to default names or jsonFormat: 'extended'. Allowing a custom render function for JSON responses gives consumers full control over API payload structure.
  • Passing the resolved format ('html' | 'json') as the third argument allows a single render handler to cleanly differentiate when consumers switch formats via ?format=... queries.
  • Reusing dirList.htmlInfo ensures that JSON renderers receive pre-calculated href, stats, and extendedInfo properties matching HTML mode.
  • Types in types/index.d.ts and types/index.tst.ts correctly allow returning unknown (serializable payloads) for ListJsonRender.

One small note: when returning a custom formatted JSON payload, if the user returns a pre-serialized JSON string (rather than an object or array), Fastify will default to text/plain. Adding reply.type('application/json') before reply.send(...) on the JSON render branch ensures consistent application/json headers regardless of whether an object or serialized string is returned.

Fixes fastify#221

Signed-off-by: Helmi Pradita <helmipraditaa@gmail.com>
@helmipradita
helmipradita force-pushed the feat/dirlist-json-render branch from 00bfae8 to c5fcc85 Compare November 10, 2026 07:05
@helmipradita

Copy link
Copy Markdown
Author

Great catch, thank you @SameRainbows!

Added reply.type('application/json') before sending on the JSON render branch and added a test covering pre-serialized JSON string returns in commit c5fcc85. All unit tests and type checks pass with 100% coverage.

@Puppo Puppo left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the PR! One compatibility regression needs addressing before this ships as a compatible feature; details inline.

Comment thread lib/dirList.js Outdated
const renderFormat = format === 'html' ? 'html' : 'json'
if (format !== 'html') {
if (typeof options.render === 'function' && options.format !== 'html') {
await reply.type('application/json').send(dirList.render(entries, route, prefix, options, renderFormat))

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Blocking] Preserve existing JSON-default listings with an HTML renderer.

list: { format: 'json', render: () => '<html>listing</html>' } was already supported: ordinary requests and ?format=json returned the built-in JSON listing, and only ?format=html invoked the renderer. This branch now invokes that existing renderer for JSON requests too. I reproduced HTTP 200 with Content-Type: application/json and the raw body <html>listing</html>, so existing clients calling response.json() break.

The base revision's json format with url parameter format test covers precisely this configuration; changing its callback to branch on format hides the compatibility regression. Can we preserve the original regression case and make JSON rendering opt-in separately, or explicitly treat this as a breaking change with migration guidance?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great point, thank you @Puppo!

Addressed in commit 4097421:

  1. Preserved list.render exclusively for HTML directory listings, restoring the original json format with url parameter format test case so that existing configurations with list: { format: 'json', render: () => '<html>' } continue returning built-in JSON for default/?format=json requests and only invoke render when ?format=html is explicitly requested.
  2. Introduced list.renderJson as the separate, opt-in custom renderer for JSON responses.
  3. Added dedicated tests for list.renderJson, serialized JSON string returns, and simultaneous render + renderJson configuration. All 394 unit tests and type checks pass with 100% coverage.

Preserve existing list.render behavior for HTML listings when format is
json (such as ?format=html override), and provide dedicated list.renderJson
for customizing JSON listings.

Signed-off-by: Helmi Pradita <helmipraditaa@gmail.com>
@helmipradita

Copy link
Copy Markdown
Author

Thanks for the thorough review @Puppo!

I have addressed this in commit 4097421 by making custom JSON directory listing rendering opt-in via a dedicated list.renderJson option:

  1. Existing list.render remains untouched for HTML rendering (preserving behavior when format: 'json' is configured with render to handle ?format=html overrides).
  2. The original regression test json format with url parameter format has been restored to its exact previous state without branching on format.
  3. Added renderJson tests verifying both custom object and serialized string JSON responses, alongside tests with both render and renderJson configured together.

@helmipradita

Copy link
Copy Markdown
Author

@Puppo — following up on your blocking review: all 17 checks are green on 4097421. That commit makes JSON rendering opt-in via list.renderJson and restores the original json format with url parameter format regression test unchanged; list.render stays HTML-only, so existing format: 'json' + HTML render configs keep returning built-in JSON. Addressed inline on 2026-11-11 but the review is still CHANGES_REQUESTED — could you re-review the current head? Happy to adjust further.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Have the render function for dirlist work for json as well

3 participants