Getting Started

Installation

npm

npm install resora

pnpm

pnpm add resora

yarn

yarn add resora

Basic Usage

Resora provides two primary primitives:

• Resource
• ResourceCollection

These classes define how data is transformed and structured before being returned as JSON.

Resource

Resource represents a single data entity.

import { Resource } from 'resora';

app.get('/:id', async () => {
  const user = { id: 1, name: 'John Doe' };

  return await new Resource(user).additional({ status: 'success' });
});

For Express and other framewords implementing Connect-style middleware, you will have to pass the response object into the contructor

import { Resource } from 'resora';

app.get('/:id', async (req, res) => {
  const user = { id: req.params.id, name: 'John Doe' };

  return await new Resource(user, res).additional({ status: 'success' });
});

Collection

ResourceCollection handles arrays and paginated datasets.

import { ResourceCollection } from 'resora';

app.get('/', async () => {
  const users = [
    { id: 1, name: 'John Doe' },
    { id: 2, name: 'Jane Doe' },
  ];

  return await new ResourceCollection(users);
});

You will also have to pass the response object into the contructor for Express and other framewords implementing Connect-style middleware.

import { ResourceCollection } from 'resora';

app.get('/', async (req, res) => {
  const users = [
    { id: 1, name: 'John Doe' },
    { id: 2, name: 'Jane Doe' },
  ];

  return await new ResourceCollection(users, res);
});

Custom Metadata

You can attach custom metadata in two ways:

• with() for class-level metadata hooks in custom resources/collections
• withMeta() for typed fluent metadata chaining in request handlers

See details and merge behavior in Writing Resources - Metadata APIs: with() vs withMeta().

Pagination & Cursor Recipes

For ready-to-copy configuration patterns, see Pagination & Cursor Quick Recipes.

Using Non-Connect Frameworks

If you are using frameworks outside H3/Express or non-Connect response styles, see Using Resora Outside H3/Express (Non-Connect Frameworks).