useProcedure

This hook takes a procedure and a parameter object, and will execute the procedure whenever the parameter object changes.

If the procedure should not be executed, you can pass false instead of a parameter object.

The execute function returned from the procedure can be used to force the procedure to be called again, even if the parameters havent changed.

Example

This example executes the procedure with a parameter passed as a React property. If the property is null, the procedure will not be executed.

import { useProcedure } from "@olenbetong/appframe-react";

export default function MyComponent({ id }) {
  let { data, error, execute, isExecuting } = useProcecure(procMyProc, id ? { ID: id } : false);

  return (
    <>
      {isExecuting && <CircularProgress indeterminate />}
      {error && <Alert severity="error">{error}</Alert>}
      <ul>
        {data[0]?.map((record) => (
          <li>{record.Message}</li>
        ))}
      </ul>
      <Button onClick={execute}>{getLocalizedString("Refresh")}</Button>
    </>
  );
}

Properties

Name	Type	Optional	Description
procedure	Procedure	no	The stored procedure to be executed
options	useProcedureOptions	yes	Options used to configure the hook

useProcedureOptions

Name	Type	Optional	Description
removeInvalidParameters	boolean	yes	Whether invalid parameters should be removed before executing the procedure. Otherwise they will be passed to the procedure, which may throw an error (default false)

Returned object properties

Name	Type	Description
isExecuting	boolean	A boolean indicating if the procedure is currently executing
data	any	Data returned by the last call to the procedure.
error	string | null	If the last call failed, contains the error message
execute	() => void	Function to force the procedure to execute even if the parameters didn't change

Type definition

declare type useProcedureOptions = {
  /**
   * If true, any parameter that does not exist in the procedure will be
   * removed before the parameters are sent to the procedure. Otherwise,
   * the procedure will be called with the parameters as they are which
   * will result in an error if some of the parameters are invalid.
   */
  removeInvalidParameters?: boolean;
};

/**
 * Executes the given procedure whenever the parameters change. If false is
 * passed instead of a parameters object, the procedure will not be called.
 *
 * @param procedure Procedure to execute
 * @param params Parameters to pass to the procedure. If false, the procedure
 * will not be called.
 * @param options Options to control how the procedure is executed
 * @returns Data returned from the procedure, a method to force a new procedure call,
 * an error if the procedure fails, and a boolean indicating if the procedure is
 * currently executing.
 */
export declare function useProcedure<TParams, TResult>(
  procedure: Procedure<TParams, TResult>,
  params: TParams | false,
  options?: useProcedureOptions
): {
  data: [] | TResult;
  error: string | RequestError | null;
  execute: () => () => void;
  isExecuting: boolean;
};
export {};