Error handling

NulvlessResult

Every method returns Promise<NulvlessResult<T>>:

type NulvlessResult<T> =
  | { data: T; error: null }
  | { data: null; error: NulvlessError };

Check error first. If it is null, data is guaranteed to be there — the union makes that true for the type checker as well, so nothing after the guard needs a non-null assertion.

const { data, error } = await nulvless.auth.signIn({ email, password });

if (error) {
  console.error(error.code, error.message, error.status_code);
  return;
}

console.log(data.access_token);

NulvlessError

message being possibly an array is worth handling once, centrally:

const text = Array.isArray(error.message) ? error.message.join(', ') : error.message;

Error codes

code is typed as ErrorCode, so your editor autocompletes every code the SDK can return. It is a union of one type per source, plus any other string, so a code added to the platform later still compiles:

import type { AuthErrorCode } from '@nulvless/nulvless-js';

const messages: Partial<Record<AuthErrorCode, string>> = {
  invalid_credentials: 'Wrong email or password.',
  registration_closed: 'Sign-up is closed.',
};

if (error) {
  showMessage(messages[error.code as AuthErrorCode] ?? error.message);
}

EdgeFunctionErrorCode lists the codes an edge function invocation answers with. Functions are called with fetch, not through the SDK, so it is not part of ErrorCode. Every code is described in Exception codes.

Exceptions instead

Set throwErrors if the surrounding code is built around try/catch:

import { NulvlessException } from '@nulvless/nulvless-js';

const nulvless = createClient(url, key, { throwErrors: true });

try {
  const { data } = await nulvless.auth.signIn(params);
} catch (err) {
  if (err instanceof NulvlessException) {
    console.error(err.code, err.status_code);
  }
}

NulvlessException carries the same code and status_code as the error object, and its message is already flattened to a string.

You can also flip it for a single call:

await nulvless.auth.signIn(params, { throwErrors: true });

Errors without a request

Some failures are decided locally, before anything is sent. Asking for the session when none is stored is the common one:

{ code: 'no_session', message: 'No active session.', status_code: 401 }

It has the same shape as any other error, so the same branch handles it. The others decided locally are network_error, request_timeout, invalid_path (an id passed as . or .., refused before it could reach another endpoint) and unknown_error — see Exception codes.