Skip to content

Clean up the serverFunctions.onError JSDoc - #1

Closed
adipascu wants to merge 1 commit into
mainfrom
docs/server-fn-error-handler-jsdoc
Closed

Clean up the serverFunctions.onError JSDoc#1
adipascu wants to merge 1 commit into
mainfrom
docs/server-fn-error-handler-jsdoc

Conversation

@adipascu

@adipascu adipascu commented Jul 29, 2026

Copy link
Copy Markdown
Owner

Follow-up review of the JSDoc added in solidjs#2262. Docs only, no behavior change.

SolidStartOptions.serverFunctions

The summary still said the option only controls "which files are processed as server functions", which stopped being true once onError was added alongside filter. It now covers both.

serverFunctions.onError

Rewritten around what a consumer has to know to write a handler. Four things were missing:

  1. A Response can arrive as the thrown value. A thrown redirect() reaches the handler before the x instanceof Response branch in handleServerFunction, so a handler that replaces everything it sees turns every thrown redirect into an error. Nothing said so, and it is the easiest way to break an app with this option.
  2. The return value is not awaited. applyServerFunctionErrorHandler calls the export and passes the result straight on, so an async handler does not do what it looks like it does.
  3. The scope is narrower than "the server". Only calls arriving over the network run through it. A server function called during rendering goes through the cloneServerReference proxy and throws straight to its caller, and API routes never touch this path at all. Worth stating for anyone wiring this up as their error reporting hook.
  4. What is returned gets serialized. Own properties travel with it, which matters given the option's main use is replacing an error that carries internal detail.

Also documents that null keeps the original alongside undefined, matching ?? thrown, and states the Response return case that previously only the tests knew about.

Dropped the paragraph explaining why the handler is named by module path instead of registered at runtime. That is design rationale for maintainers, not something a consumer needs while writing vite.config.ts.

ServerFunctionErrorHandler

This is the type consumers import from @solidjs/start/server when writing their handler, and it had no doc at all. Now carries @param, @returns, and a worked @example, mirroring the shape of the serialization.plugins docs in fns/plugins.ts. The example passes Response control flow through, so copying it does not break redirects.

/** @internal */

Removed. It was the only occurrence in the repo, packages/start/tsconfig.json does not set stripInternal, and there is no API Extractor or TypeDoc in the pipeline, so it stripped nothing. applyServerFunctionErrorHandler is not re-exported from any public entry point, so it is unreachable for consumers either way.

apps/tests/src/server-fn-error.ts

Punctuation, and refers to the sibling as src/seroval-plugins.ts the way config/index.ts does. The rationale in this file is kept: it is a maintainer-facing fixture, and the note about why returning undefined matters would otherwise be broken silently.

oxfmt --check passes on all three files.

@adipascu
adipascu force-pushed the docs/server-fn-error-handler-jsdoc branch 4 times, most recently from 3b80c45 to b695aa0 Compare July 29, 2026 15:35
@adipascu adipascu changed the title Document the serverFunctions.onError contract for consumers Expand the serverFunctions.onError JSDoc Jul 29, 2026
@adipascu
adipascu force-pushed the docs/server-fn-error-handler-jsdoc branch from b695aa0 to cbe53fc Compare July 29, 2026 15:37
@adipascu adipascu changed the title Expand the serverFunctions.onError JSDoc Clean up the serverFunctions.onError JSDoc Jul 29, 2026
@adipascu
adipascu force-pushed the docs/server-fn-error-handler-jsdoc branch 3 times, most recently from ad9818f to a9ef547 Compare July 29, 2026 15:50
@adipascu
adipascu force-pushed the docs/server-fn-error-handler-jsdoc branch from a9ef547 to c98aff2 Compare July 29, 2026 15:51
@adipascu adipascu closed this Jul 29, 2026
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.

1 participant