Document "declarative fetch" (`deno serve`)

[rbetts]

CLI version 1.43 includes a new subcommand, deno serve that allows a user to call fetch with export default directly without Deno imports. The deno serve subcommand implies allow-net permissions.

export default {
   fetch(req) { return new Response('hello world!\n'); }
}

This requires a few document updates. I was able to find:

• [x] Update https://docs.deno.com/runtime/manual/tools/ with the new subcommand.
• [x] Update https://docs.deno.com/subhosting/manual/#quick-start-example to use declarative fetch vs. Deno.Serve().
• [x] Update https://docs.deno.com/subhosting/manual/projects_and_deployments#creating-a-deployment-for-a-project to use declarative fetch vs. Deno.Serve()
• [x] Update https://apidocs.deno.com/#post-/projects/-projectId-/deployments API example to use declarative fetch vs. Deno.Serve()

[bartlomieju]

PR that adds it: https://github.com/denoland/deno/pull/23511/files

[thisisjofrank]

https://github.com/denoland/deno-docs/pull/561

[jsejcksn]

@thisisjofrank The docs still don't appear to provide a schema or types. Either would be very helpful in understanding the constraints of what is expected to be exported. From a glance at the registration source code in the associated implementation commit, it looks like a module is expected with only a fetch field… which is a function that is only called with a single parameter of type Request, and should return Response | Promise<Response>:

TS Playground

declare const declarativeDefaultExport: {
  fetch: (request: Request) => Response | Promise<Response>;
};

export default declarativeDefaultExport;

This is subtly different from Deno.ServeHandler, which accepts Deno.ServeHandlerInfo as the second parameter:

TS Playground

declare namespace Deno {
  export type NetAddr = {
    transport: "tcp" | "udp";
    hostname: string;
    port: number;
  };

  export type ServeHandlerInfo = {
    remoteAddr: Deno.NetAddr;
    completed: Promise<void>;
  };

  export type ServeHandler = (
    request: Request,
    info: ServeHandlerInfo,
  ) => Response | Promise<Response>;
}

I am not aware of discussion regarding the choice to not provide connection information to declarative server code — perhaps it is by design and not an oversight? Regardless, I think better documentation is still needed to clarify things for users. It would also be good to describe the available unique CLI arguments (--host and --port) and list their defaults. By the way, can --host be changed to --hostname for Deno 2.0?

[jsejcksn]

(Following up on my previous comment)

Refs:

• https://github.com/denoland/deno/issues/23725
• https://github.com/denoland/deno/pull/24879