nostalgie/functions

The nostalgie/functions package exposes some tools to easily interact with Server Functions.

IMPORTANT: The useQueryFunction and useMutationFunction hooks must be invoked with an actual reference to the Server Function that you want to invoke. Don't worry though, the Server Function and its dependencies won't actually be included in your front-end bundles. The Nostalgie compiler takes care of swapping out the actual function with an internal representation at build time.

Using a reference to the actual function allows us to give rich type hinting on the shape of required arguments and on the data ultimately returned by the function. It also means that information is equally available to JavaScript and TypeScript users working in an environment with the TypeScript language services.

useQueryFunction(queryFunction, args, [options])

A React Hook that returns a live observer of the result of invoking a Server Function. Dependending on the options used, this may return cached ('stale') data from a previous invocation or even an invocation that happened during server rendering.

• queryFunction - a reference to the actual Server Function that you want to invoke.
• args - an array of arguments that will be passed to the Server Function. These must be serializable to JSON as they may sometimes be passed via HTTP request.
• options - optional configuration for the query, which are identical to useQuery options in react-query except that queryKey and queryFn cannot be provided as Nostalgie will determine these automatically.

Returns the query observer object returned by useQuery. Please refer to the (excellent) react-query documentation for more information.

Example: Render the result of a Server Function

In this example, we want to show the result of calling process.resourceUsage() in the browser and refresh this value periodically.

./src/functions.js:

export function getResourceUsage() {
  return process.resourceUsage();
}

./src/ResourceUsage.jsx:

import { useQueryFunction } from 'nostalgie/functions';
import * as React from 'react';
import { getResourceUsage } from '../../../functions';

export function ResourceUsage() {
  // The `usage` object is an object that will update over time as the lifecycle
  // of the query progresses.
  const usage = useQueryFunction(getResourceUsage, [], {
    refetchInterval: 10000, // Every ten seconds
  });

  // In the real world, we might want to handle different states differently
  if (!usage.isSuccess) {
    return <pre>Loading...</pre>;
  }

  // Show our resource usage as formatted JSON
  return <pre>{JSON.stringify(usage.data, null, 2)}</pre>;
}

Live result:

{
  "userCPUTime": 760000,
  "systemCPUTime": 30000,
  "maxRSS": 69312,
  "sharedMemorySize": 0,
  "unsharedDataSize": 0,
  "unsharedStackSize": 0,
  "minorPageFault": 0,
  "majorPageFault": 0,
  "swappedOut": 0,
  "fsRead": 0,
  "fsWrite": 0,
  "ipcSent": 0,
  "ipcReceived": 0,
  "signalsCount": 0,
  "voluntaryContextSwitches": 0,
  "involuntaryContextSwitches": 0
}

useMutationFunction(queryFunction, [options])

A React Hook that returns a live observer of the a mutating Server Function. The server function will not be invoked until the .mutate() method is invoked.

• queryFunction - a reference to the actual Server Function that you want to invoke.
• options - optional configuration for the query, which are identical to useMutation options in react-query except that mutationFn cannot be provided as Nostalgie will determine it automatically.
  • mutate(args) - invoke the mutation function in the background, where:
    • args - an array of arguments that will be passed to the Server Function. These must be serializable to JSON as they may sometimes be passed via HTTP request.
  • mutateAsync(args) - invoke the mutation function, returning a Promise for its outcome, where:
    • args - an array of arguments that will be passed to the Server Function. These must be serializable to JSON as they may sometimes be passed via HTTP request.

Returns the mutation observer object returned by useMutation. Please refer to the (excellent) react-query documentation for more information.