Resora

Resora is a structured API response layer for Node.js and TypeScript backends.

It provides a clean, explicit way to transform data into consistent JSON responses and automatically send them to the client. Resora supports single resources, collections, pagination and cursor metadata, conditional attributes, and response customization while remaining framework-agnostic and strongly typed.

Resora is designed for teams that care about long-term maintainability, predictable API contracts, and clean separation of concerns.

---

What Problem Does Resora Solve?

In most Node.js backends:

• Controllers shape JSON directly
• Response formats drift over time
• Pagination logic is duplicated
• Metadata handling is inconsistent

Resora introduces a dedicated response transformation layer that removes these concerns from controllers and centralizes response structure in one place.

---

Core Capabilities

• Explicit data-to-response transformation
• Automatic JSON response dispatch
• First-class collection support
• Built-in pagination metadata handling
• Built-in cursor metadata handling
• Conditional attribute helpers (when, whenNotNull, mergeWhen)
• Configurable response envelope (wrap, rootKey, factory)
• Configurable pagination URL/link output (baseUrl, pageName, key mapping)
• Predictable and consistent response contracts
• Strong TypeScript typing
• Transport-layer friendly (Express, H3, and others)

---

Basic Example

Single Resource

import { Resource } from 'resora';

class UserResource extends Resource {
  data() {
    return this.toObject();
  }
}

return new UserResource(user).additional({
  status: 'success',
  message: 'User retrieved',
});

Response:

{
  "data": {
    "id": 1,
    "name": "John"
  },
  "status": "success",
  "message": "User retrieved"
}

---

Collection with Pagination

import { ResourceCollection } from 'resora';

class UserCollection<R extends User[]> extends ResourceCollection<R> {
  collects = UserResource;

  data() {
    return this.toObject();
  }
}

return new UserCollection({
  data: users,
  pagination: {
    currentPage: 1,
    lastPage: 10,
    from: 1,
    to: 10,
    perPage: 10,
    total: 100,
    path: '/users',
  },
}).additional({
  status: 'success',
  message: 'Users retrieved',
});

Response:

{
  "data": [...],
  "links": {
    "last": "https://localhost/users?page=10"
  },
  "meta": {
    "from": 1,
    "to": 10,
    "per_page": 10,
    "total": 100,
    "current_page": 1,
    "last_page": 10,
    "path": "/users"
  },
  "status": "success",
  "message": "Users retrieved"
}

---

Architectural Positioning

Resora sits between your application logic and the HTTP layer.

• Controllers handle request flow
• Services handle business logic
• Resora handles response structure

This separation ensures:

• Stable API contracts
• Minimal controller logic
• Clear ownership of response shape

---

Design Principles

• Explicit over implicit behavior
• Separation of concerns
• Minimal abstraction cost
• Strong typing as a first-class feature
• Framework independence

---

Framework Compatibility

Resora is not tied to a specific HTTP framework.

It works with:

• Express
• H3
• Any application or framework that supports Connect-style middleware

Adapters can be added without changing application logic.

Plugin System

Resora exposes a first-class plugin registry for opt-in integrations and lifecycle extensions.

import { registerPlugin } from 'resora';
import { clearRouterExpressPlugin } from '@resora/plugin-clear-router';

registerPlugin(clearRouterExpressPlugin);

Plugins can:

• hook into serialization and response dispatch
• inject framework integrations without core changes
• register reusable transformation utilities

Conditional Rendering Example

class UserResource extends Resource {
  data() {
    return {
      id: this.id,
      email: this.whenNotNull(this.email),
      role: this.when(this.isAdmin, 'admin'),
      ...this.mergeWhen(this.isAdmin, { permissions: ['manage-users'] }),
    };
  }
}

Falsy/null attributes are omitted from the final serialized payload.

---

When to Use Resora

Resora is a good fit if you:

• Build APIs with long-term maintenance in mind
• Care about response consistency across teams
• Want pagination and metadata handled once
• Prefer explicit structure over ad-hoc JSON responses

It is intentionally not opinionated about routing, validation, or persistence.

---

Documentation

• Getting Started: https://arkstack-hq.github.io/resora/guide/getting-started
• Configuration: https://arkstack-hq.github.io/resora/guide/configuration
• Conditional Rendering: https://arkstack-hq.github.io/resora/guide/conditional-attributes
• Pagination & Cursor Recipes: https://arkstack-hq.github.io/resora/guide/pagination-cursor-recipes

---

License

MIT