@microsoft/rayfin-functions

SDK reference for FunctionClient, FunctionsSchema, InvokeOptions, FunctionsError, and typed client.functions invocations.

Changed in 1.36

@microsoft/rayfin-functions is the client-side SDK package behind client.functions.<name>.invoke(...). Server-side function authoring uses @microsoft/fabric-user-data-functions.

Installation

New Rayfin projects get this package through @microsoft/rayfin-client. Add it directly only when you import FunctionsError, FunctionClient, or the types from this package yourself.

npm install @microsoft/rayfin-functions

Exports

Export	Kind	Purpose
`FunctionClient<TInput, TOutput>`	Class	Client for one named function.
`FunctionsError`	Class	Function invocation error extending `SdkError`.
`createFunctionsApi<TSchema>(apiClient)`	Function	Creates the typed `client.functions` proxy.
`FunctionInvocationResponse<TOutput>`	Type	Transport envelope returned by the backend before `invoke()` unwraps `output`.
`InvokeOptions`	Type	Per-call headers and timeout.
`FunctionsSchema`	Type	Map of function names to `{ input, output }`.
`TypedFunctionClients<TSchema>`	Type	Map from schema keys to typed `FunctionClient` instances.

`FunctionsSchema`

type FunctionsSchema = Record<string, { input: any; output: any }>;

Generated projects export an AppFunctionsSchema from rayfin/functions/src/types.ts:

rayfin/functions/src/types.ts

export type AppFunctionsSchema = {
  greet: {
    input: { firstName: string; lastName: string };
    output: string;
  };
  getEntries: {
    input: Record<string, never>;
    output: { id: string; message: string }[];
  };
};

Pass that schema as the second type parameter to RayfinClient:

src/services/rayfinClient.ts

import { RayfinClient } from '@microsoft/rayfin-client';
import type { AppSchema } from '../../rayfin/data/schema';
import type { AppFunctionsSchema } from '../../rayfin/functions/src/types.js';

export const client = new RayfinClient<AppSchema, AppFunctionsSchema>({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL,
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

`FunctionClient`

class FunctionClient<TInput = any, TOutput = any> {
  constructor(apiClient: ApiClient, functionName: string);

  invoke(
    ...args: TInput extends void | Record<string, never>
      ? [params?: undefined, options?: InvokeOptions]
      : [params: TInput, options?: InvokeOptions]
  ): Promise<TOutput>;
}

invoke() returns the function output directly as Promise<TOutput>. It does not return the transport envelope.

Function shape	Call form
Input function	`invoke(params)` or `invoke(params, options)`
No-input function	`invoke()` or `invoke(undefined, options)`

A lone argument is always treated as function input, never as options.

`InvokeOptions`

interface InvokeOptions {
  headers?: Record<string, string>;
  timeoutMs?: number;
}

timeoutMs defaults to 250,000 ms and is capped at that same Fabric UDF host limit. Non-positive, non-finite, or missing values use the default.

Invocation route

When the underlying ApiClient has functionsBaseUrl, FunctionClient posts to:

${functionsBaseUrl}/api/<functionName>

Otherwise it posts to the deployed Fabric route:

${baseUrl}/functions/<functionName>/invoke

Errors

FunctionClient.invoke() throws on failure. Catch FunctionsError before a generic error handler when you need function-specific messages or codes.

import { FunctionsError } from '@microsoft/rayfin-functions';
import { NetworkError } from '@microsoft/rayfin-lib';

try {
  const result = await client.functions.greet.invoke({
    firstName: 'Ada',
    lastName: 'Lovelace',
  });
  console.log(result);
} catch (error) {
  if (error instanceof FunctionsError) {
    console.error(error.code, error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network failure while invoking the function.');
  } else {
    throw error;
  }
}

FunctionClient.invoke() throws on failure:

Failure	Error
Backend response contains `errors` or non-success `status`	`FunctionsError` with code `FUNCTION_EXECUTION_ERROR`.
Unexpected invocation failure	`FunctionsError` with code `UNKNOWN_FUNCTION_ERROR`.
Network failure	`NetworkError` from `@microsoft/rayfin-lib`.
Other SDK failure	`SdkError` from `@microsoft/rayfin-lib`.

The backend invocationId is logged with console.debug as [rayfin-functions] <name> invocationId=<id>.

Full exported surface

export { FunctionsError, createFunctionsApi, FunctionClient } from './Functions.js';
export type {
  FunctionInvocationResponse,
  InvokeOptions,
  TypedFunctionClients,
} from './Functions.js';
export type { FunctionsSchema } from './FunctionsSchema.js';

`FunctionInvocationResponse`

interface FunctionInvocationResponse<TOutput = any> {
  functionName: string;
  invocationId: string;
  status: string;
  output: TOutput;
  errors: Array<string | Record<string, any>>;
}

This is the wire envelope. invoke() unwraps and returns output, auto-parsing JSON-encoded output strings and inner { output: <value> } envelopes when present.

Something wrong on this page?Report an issueEdit this page

@microsoft/rayfin-functions

On this page