Resourceful Decorators

Lucid Resourceful provides a comprehensive set of decorators that enhance AdonisJS Lucid models with metadata-driven functionality. These decorators add validation, access control, OpenAPI schema generation, and type safety to your model properties and relationships.

Overview

The resourceful decorators extend the standard Lucid decorators with additional capabilities:

• Type Validation: Built-in Joi schema validation for all property types
• Access Control: Field-level read/write permissions via ACL filters
• OpenAPI Integration: Automatic schema generation for API documentation
• Data Transformation: Automatic prepare/consume functions for type safety
• Metadata Storage: Rich metadata for runtime introspection

Core Decorators

Column Decorators

The @resourcefulColumn decorator and its type-specific variants handle database columns with enhanced functionality:

• @resourcefulColumn - Generic column decorator with custom type definition
• @resourcefulColumn.string - String columns with automatic string handling
• @resourcefulColumn.number - Numeric columns with number validation
• @resourcefulColumn.integer - Integer columns with integer validation
• @resourcefulColumn.bigint - BigInt columns with bigint handling
• @resourcefulColumn.unsignedint - Unsigned integer columns
• @resourcefulColumn.boolean - Boolean columns with boolean conversion
• @resourcefulColumn.date - Date columns with date handling
• @resourcefulColumn.dateTime - DateTime columns with timestamp handling
• @resourcefulColumn.binary - Binary/buffer columns
• @resourcefulColumn.object - JSON object columns
• @resourcefulColumn.array - JSON array columns

Computed Accessor Decorators

The @resourcefulComputed decorator and its variants handle computed properties:

• @resourcefulComputed - Generic computed accessor with custom type
• @resourcefulComputed.string - String computed accessors
• @resourcefulComputed.number - Number computed accessors
• @resourcefulComputed.integer - Integer computed accessors
• @resourcefulComputed.bigint - BigInt computed accessors
• @resourcefulComputed.unsignedint - Unsigned integer computed accessors
• @resourcefulComputed.boolean - Boolean computed accessors
• @resourcefulComputed.date - Date computed accessors
• @resourcefulComputed.dateTime - DateTime computed accessors
• @resourcefulComputed.binary - Binary computed accessors
• @resourcefulComputed.object - Object computed accessors
• @resourcefulComputed.array - Array computed accessors

Relationship Decorators

The relationship decorators provide enhanced relationship handling with resourceful features:

• @resourcefulBelongsTo - BelongsTo relationships
• @resourcefulHasOne - HasOne relationships
• @resourcefulHasMany - HasMany relationships
• @resourcefulManyToMany - ManyToMany relationships
• @resourcefulHasManyThrough - HasManyThrough relationships

Common Configuration Options

All resourceful decorators support a common set of configuration options:

Type Definition

type: ResourcefulDataType // Required - defines the field type and validation

Access Control

readAccessControlFilters: ResourcefulAccessControlFilter[]  // Controls read access
writeAccessControlFilters: ResourcefulAccessControlFilter[] // Controls write access

Metadata

nullable: boolean           // Whether the field can be null
description?: string        // Field description for documentation
default?: any              // Default value
deprecated?: boolean       // Mark field as deprecated
example?: string           // Example value for documentation
externalDocs?: ExternalDocumentationObject // External documentation link

Validation Scoping

validationScoper?: ValidationScoper // Dynamic validation modification

Quick Examples

Basic Column Usage

import { BaseModel } from '@adonisjs/lucid/orm'
import { compose } from '@adonisjs/core/helpers'
import { withResourceful, resourcefulColumn } from '@nhtio/lucid-resourceful'
import { ResourcefulStringType, ResourcefulUnsignedIntegerType } from '@nhtio/lucid-resourceful/definitions'

export default class User extends compose(BaseModel, withResourceful({ name: 'User' })) {
  @resourcefulColumn({ 
    isPrimary: true, 
    type: ResourcefulUnsignedIntegerType({ readOnly: true }) 
  })
  declare id: number

  @resourcefulColumn.string({ 
    type: ResourcefulStringType({ minLength: 2, maxLength: 100 }),
    nullable: false
  })
  declare name: string

  @resourcefulColumn.dateTime({ autoCreate: true, autoUpdate: true })

  declare updatedAt: DateTime
}

Access Control Example

@resourcefulColumn.string({
  type: ResourcefulStringType(),
  nullable: false,
  readAccessControlFilters: [
    (ctx) => ctx.auth.user?.role === 'admin'
  ],
  writeAccessControlFilters: [
    (ctx) => ctx.auth.user?.role === 'admin'

  ]
})
declare sensitiveField: string

Relationship Example

@resourcefulHasMany(() => Post, { 
  foreignKey: 'user_id',
  readAccessControlFilters: [
    (ctx) => !!ctx.auth.user
  ]
})
declare posts: HasMany<typeof Post>

API Reference

For complete API documentation, see:

• resourcefulColumn function
• resourcefulComputed function
• resourcefulBelongsTo function
• resourcefulHasMany function
• resourcefulHasManyThrough function
• resourcefulManyToMany function

Data Types

All decorators require a type parameter that must be a ResourcefulDataType instance. See the Data Type Definitions for details on available data types and their configuration options.

Next Steps

• Learn about individual decorators in their dedicated documentation pages
• Explore Data Type Definitions for available types and their options
• See Validation for Joi schema building and custom validation
• See Configuration for mixin setup options
• Check CRUD Operations for using decorated models