Skip to content

docs: improve requested from the $app/server module #15900

Description

@hyunbinseo

(Update) The Client-requested refreshes docs seem to have most of the concerns resolved with the latest API. The requested docs could point here in the meantime. This isn't the first time I was referencing a less friendly, more API explanatory documentation, so such reference link could be really helpful.


Describe the problem

Current docs is not intuitive.

In the context of a remote command or form request ...

  • What does 'context' mean here?
  • Is that query same as $app/server.query? It does support the refresh method.
import { requested } from '$app/server';

for (const { arg, query } of requested(getPost, 5)) {
  // `arg` is the validated argument; `query` is bound to the client's
  // cache key. It's safe to throw away this promise -- SvelteKit will
  // await it and forward any errors to the client.
  void query.refresh();
}

The original PR #15562 had a more intuitive code block:

  • requested should be called inside command or form callback.
// so this probably is a `*.remote.ts` file

import { query, command, requested } from '$app/server';

export const getPullRequests = query(GetPullRequestSchema, async () => {});

export const createPullRequest = command(CreatePullRequestSchema, async (args) => {
  /* do the stuff to create the pull request */

  // if your query uses async validators, you can also `for await` this.
  // it will run validation in parallel and yield results as they're available.
  for (const arg of requested(getPullRequests, 5)) {
    void getPullRequests(arg).refresh();
  }
});

Describe the proposed solution

Rough ideation. The #15562 PR body was much easier for me to understand than the current docs.


All query instance(s) refresh requested by the client can be accessed inside the command and form callbacks using the requested module.

import { command, requested } from '$app/server';

export const createPullRequest = command(CreatePullRequestSchema, async (data) => {
  /* do the stuff to create the pull request */

  for (const req of requested(
    getPost, // query function (vanilla batch, live)
    5, // limit
  )) {
    void req.query.refresh();
  }
});

Alternatives considered

No response

Importance

nice to have

Additional Information

No response

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions