DOCSEARCHbyAlgolia
Submit Docs

Arkos.js Documentation

website·Indexed 31 days ago

https://arkosjs.com

A framework that integrates with Prisma ORM to provide auto-generated RESTful endpoints, JWT-based authentication, and Role-Based Access Control (RBAC). It features a file-based convention system with built-in support for controllers, services, validators, and interceptors to streamline the development of Node.js APIs.

Tokens
83.9K
Snippets
492
Records
558
Agent score
59%

What's inside Arkos

  1. Overview of the File Upload Controller

    The fileUploadController provides programmatic access to Arkos's file upload system. While Arkos provides default endpoints at /api/uploads/:fileType, using this controller allows developers to create custom routes with specialized middleware, custom business logic, and granular access control (e.g., restricting users to only update their own avatars).
    import fileUploadController from "arkos/controllers";

  2. Overview of Arkos Validation Libraries

    Arkos supports two validation libraries: Zod and class-validator. Both provide equivalent generation commands that automatically produce files based on your Prisma schema. These generated schemas and DTOs can be passed directly into a RouteHook or ArkosRouter route configuration.

    • Zod schemas are generated to: src/modules/<module>/schemas/
    • Class-validator DTOs are generated to: src/modules/<module>/dtos/

  3. Introduction to @arkosjs/websockets-client

    The @arkosjs/websockets-client is a core client built on top of socket.io-client. It provides several critical enhancements over a raw socket connection, including:

    • Automatic _meta injection to match server expectations for deduplication and freshness.
    • Improved ergonomics for acknowledgments (ack), retries, and timeouts.
    • Reactive connection status tracking.

    Framework-specific packages (React, Vue, Svelte, Solid, Angular) act as thin adapters over this core client, providing framework-native reactivity primitives while maintaining the same underlying API.

  4. Overview of Arkos Authentication and Authorization Hooks

    Arkos uses a two-step pipeline for protected routes: first, authService.authenticate extracts and verifies the JWT to set req.user; second, authService.authorize checks the user's roles or permissions against route access rules. Hooks allow developers to execute custom logic before, after, or upon failure of these steps without replacing the built-in behavior. Hooks are defined globally in ArkosConfig and apply to all protected routes, including auto-generated Prisma model routes, built-in auth endpoints, and custom ArkosRouter routes.

  5. Overview of Arkos Service Hooks

    Service Hooks run logic at the service layer every time a BaseService method is called. Unlike HTTP interceptors, which only fire during API calls, Service Hooks execute for all service calls, including those from background jobs, CLI commands, or other services. They are ideal for business logic, data validation, and side effects that must occur regardless of the entry point.

  6. Overview of Arkos.js Framework

    Arkos.js is a modern JavaScript/TypeScript framework designed for building secure and scalable Node.js RESTful applications. It acts as an abstraction layer over Express (server framework) and Prisma (ORM), combining Functional Programming (FP) and Object-Oriented Programming (OOP) paradigms. While it provides high-level tools and modular architecture (similar to NestJS), it allows developers to write plain Express or Prisma code directly when needed.

  7. Overview of Arkos Dynamic Permission Mode

    Dynamic mode is a database-driven permission system where roles and permissions are stored in the database (AuthRole, AuthPermission, and UserRole models). This allows for runtime updates to roles and permissions without requiring a redeploy, making it suitable for multi-tenant applications and SaaS platforms. Authentication must be configured before enabling Dynamic mode.

  8. Overview of Arkos Interceptors

    Interceptors allow developers to run custom logic before, after, or on error of auto-generated endpoints, such as Prisma model routes, authentication routes, and file upload routes. They enable the injection of business logic (e.g., setting default values, logging, notifications) without rewriting the built-in handlers. Interceptors work alongside Route Hooks for a complete customization experience.

  9. Overview of Arkos BaseController

    The BaseController class provides standardized RESTful API endpoints for any Prisma model in an Arkos application. It implements a consistent interface for common CRUD operations to reduce code duplication. While primarily an internal utility for auto-generated endpoints, it is exposed to developers to allow customization of the end handlers for CRUD operations.

  10. Understand Arkos Generated Routes boot order

    Arkos automatically registers three categories of routes: Prisma Model Routes, Authentication Routes, and File Upload Routes. These are registered at boot time in the following order:

    1. Built-in Arkos middleware (e.g., body parser, CORS).
    2. Custom routers and middleware (registered via app.use() before app.listen() in v1.6+ or arkos.init({ use: [] }) in pre-1.6).
    3. Auto-generated routes.

    Because custom routes are registered before generated ones, custom route definitions always take precedence over generated endpoints.

  11. Implement business logic using Services in Arkos

    Services in Arkos are used to house business logic, acting as an intermediary between Controllers (HTTP layer) and the database or external systems. This separation ensures that logic is testable and reusable across different entry points, such as HTTP handlers, background jobs, or other services.
    import postRepository from "./post.repository";

class PostService {
  async getFeatured() {
    return postRepository.findMany({ where: { featured: true } });
  }

  async publish(id: string) {
    return postRepository.update({
      where: { id },
      data: { publishedAt: new Date() },
    });
  }
}

const postService = new PostService();
export default postService;

  12. Standardize application errors using AppError

    AppError is a specialized error class in Arkos that extends the native JavaScript Error class. It is used to create a consistent error structure, map errors to HTTP status codes, and distinguish between operational errors (expected issues like invalid input) and programming errors (bugs).