@nhtio/lucid-resourceful 0.1.0-master-1570171e → 0.1.0-master-3ec631a4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nhtio/lucid-resourceful",
-  "version": "0.1.0-master-1570171e",
+  "version": "0.1.0-master-3ec631a4",
   "description": "A decorator-driven AdonisJS library that lets you annotate Lucid ORM models with metadata to automatically generate CRUD controllers, validation rules, OpenAPI schemas, and a unified query interface.",
   "keywords": [],
   "author": "Jak Giveon <jak@nht.io>",

package/private/decorators.d.ts

@@ -48,7 +48,7 @@ export type RelatedModelRelationOptions<RelatedModel extends LucidModel> = Relat
  * ```
  */
 export type HasManyThroughRelationOptions<RelatedModel extends LucidModel> = Omit<ThroughRelationOptions<RelatedModel, LucidModel, HasManyThrough<RelatedModel>>, 'throughModel'>;
-export type DataTypeColumnOptions = Omit<ColumnOptions, 'prepare' | 'consume'>;
+export type DataTypeColumnOptions = ColumnOptions;
 export type DataTypeComputedOptions = Omit<ComputedOptions, 'prepare' | 'consume'>;
 /**
  * Decorator to define a resourceful column on a Lucid model property.
@@ -69,15 +69,15 @@ export type DataTypeComputedOptions = Omit<ComputedOptions, 'prepare' | 'consume
  */
 export declare function resourcefulColumn<Schema extends AnySchema = ResourcefulPropertySchema>(options?: Partial<ColumnOptions> & Partial<ResourcefulColumnDefinition<Schema>>): (target: any, propertyKey: string) => void;
 export declare namespace resourcefulColumn {
-    var string: (options?: Partial<DataTypeColumnOptions> & Partial<ResourcefulColumnDefinition<StringSchema>>) => (target: any, propertyKey: string) => void;
+    var string: (options?: Partial<ColumnOptions> & Partial<ResourcefulColumnDefinition<StringSchema>>) => (target: any, propertyKey: string) => void;
     var date: (options?: Partial<DateColumnOptions> & Partial<ResourcefulColumnDefinition<DateSchema>>) => (target: any, propertyKey: string) => void;
     var dateTime: (options?: Partial<DateColumnOptions> & Partial<ResourcefulColumnDefinition<DateSchema>>) => (target: any, propertyKey: string) => void;
-    var binary: (options?: Partial<DataTypeColumnOptions> & Partial<ResourcefulColumnDefinition<BinarySchema>>) => (target: any, propertyKey: string) => void;
-    var number: (options?: Partial<DataTypeColumnOptions> & Partial<ResourcefulColumnDefinition<NumberSchema>>) => (target: any, propertyKey: string) => void;
-    var integer: (options?: Partial<DataTypeColumnOptions> & Partial<ResourcefulColumnDefinition<NumberSchema>>) => (target: any, propertyKey: string) => void;
-    var bigint: (options?: Partial<DataTypeColumnOptions> & Partial<ResourcefulColumnDefinition<NumberSchema>>) => (target: any, propertyKey: string) => void;
-    var unsignedint: (options?: Partial<DataTypeColumnOptions> & Partial<ResourcefulColumnDefinition<NumberSchema>>) => (target: any, propertyKey: string) => void;
-    var boolean: (options?: Partial<DataTypeColumnOptions> & Partial<ResourcefulColumnDefinition<BooleanSchema>>) => (target: any, propertyKey: string) => void;
+    var binary: (options?: Partial<ColumnOptions> & Partial<ResourcefulColumnDefinition<BinarySchema>>) => (target: any, propertyKey: string) => void;
+    var number: (options?: Partial<ColumnOptions> & Partial<ResourcefulColumnDefinition<NumberSchema>>) => (target: any, propertyKey: string) => void;
+    var integer: (options?: Partial<ColumnOptions> & Partial<ResourcefulColumnDefinition<NumberSchema>>) => (target: any, propertyKey: string) => void;
+    var bigint: (options?: Partial<ColumnOptions> & Partial<ResourcefulColumnDefinition<NumberSchema>>) => (target: any, propertyKey: string) => void;
+    var unsignedint: (options?: Partial<ColumnOptions> & Partial<ResourcefulColumnDefinition<NumberSchema>>) => (target: any, propertyKey: string) => void;
+    var boolean: (options?: Partial<ColumnOptions> & Partial<ResourcefulColumnDefinition<BooleanSchema>>) => (target: any, propertyKey: string) => void;
     var object: (options?: Partial<ColumnOptions> & Partial<ResourcefulColumnDefinition<ObjectSchema>>) => (target: any, propertyKey: string) => void;
     var array: (options?: Partial<ColumnOptions> & Partial<ResourcefulColumnDefinition<ArraySchema>>) => (target: any, propertyKey: string) => void;
 }

package/private/lucene_to_lucid_translator.d.ts

@@ -1,5 +1,5 @@
-import type { ModelKeysContract } from '@adonisjs/lucid/types/model';
 import type { QueryClientContract } from '@adonisjs/lucid/types/database';
+import type { LucidModel, ModelKeysContract } from '@adonisjs/lucid/types/model';
 import type { DatabaseQueryBuilderContract } from '@adonisjs/lucid/types/querybuilder';
 import type { ComparisonOperatorToken, EmptyExpression, FieldToken, ImplicitFieldToken, LiteralExpressionToken, LogicalExpressionToken, RangeExpressionToken, RegexExpressionToken, TagToken, UnaryOperatorToken, ParenthesizedExpressionToken, ExpressionToken, ParserAst } from 'liqe';
 /**
@@ -9,179 +9,24 @@ import type { ComparisonOperatorToken, EmptyExpression, FieldToken, ImplicitFiel
  */
 export interface LuceneFilteredDatabaseQueryBuilderContract extends DatabaseQueryBuilderContract {
 }
-/**
- * Applies an empty expression AST node to a database query.
- * Empty expressions are no-op operations that don't modify the query.
- *
- * @template T - The result type for the query builder
- * @param _ast - The empty expression AST node
- * @param _query - The database query builder to modify
- * @param _attributesToColumns - Mapping of model attributes to database columns
- * @param _primaryKey - The primary key column name
- * @param _tableName - The table name
- * @param _allowedColumns - Optional array of allowed column names for filtering
- */
-export declare const applyLuceneEmptyExpressionAst: (_ast: EmptyExpression, _query: LuceneFilteredDatabaseQueryBuilderContract, _attributesToColumns: ModelKeysContract, _primaryKey: string, _tableName: string, _allowedColumns?: string[] | undefined) => void;
-/**
- * Applies a logical expression AST node (AND/OR) to a database query.
- * Handles logical operations between two expressions with proper SQL grouping.
- *
- * @template T - The result type for the query builder
- * @param ast - The logical expression AST node containing left/right operands and operator
- * @param query - The database query builder to modify
- * @param attributesToColumns - Mapping of model attributes to database columns
- * @param primaryKey - The primary key column name
- * @param tableName - The table name
- * @param allowedColumns - Optional array of allowed column names for filtering
- */
-export declare const applyLuceneLogicalExpressionAst: (ast: LogicalExpressionToken, query: LuceneFilteredDatabaseQueryBuilderContract, attributesToColumns: ModelKeysContract, primaryKey: string, tableName: string, allowedColumns?: string[] | undefined) => void;
-/**
- * Applies a parenthesized expression AST node to a database query.
- * Maintains logical grouping by wrapping the inner expression in a WHERE clause.
- *
- * @template T - The result type for the query builder
- * @param ast - The parenthesized expression AST node containing the inner expression
- * @param query - The database query builder to modify
- * @param attributesToColumns - Mapping of model attributes to database columns
- * @param primaryKey - The primary key column name
- * @param tableName - The table name
- * @param allowedColumns - Optional array of allowed column names for filtering
- */
-export declare const applyLuceneParenthesizedExpressionAst: (ast: ParenthesizedExpressionToken, query: LuceneFilteredDatabaseQueryBuilderContract, attributesToColumns: ModelKeysContract, primaryKey: string, tableName: string, allowedColumns?: string[] | undefined) => void;
-/**
- * Applies an empty expression to a database query for a specific column.
- * Handles queries for null or empty values.
- *
- * @template T - The result type for the query builder
- * @param column - The database column name to query
- * @param _expression - The empty expression (unused)
- * @param operator - The comparison operator token
- * @param query - The database query builder to modify
- * @param _attributesToColumns - Mapping of model attributes to database columns (unused)
- * @param _primaryKey - The primary key column name (unused)
- * @param _tableName - The table name (unused)
- * @param allowedColumns - Optional array of allowed column names for filtering
- */
-export declare const applyLuceneEmptyExpression: (column: string, _expression: EmptyExpression, operator: ComparisonOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract, _attributesToColumns: ModelKeysContract, _primaryKey: string, _tableName: string, _allowedColumns?: string[] | undefined) => void;
-/**
- * Applies a literal expression to a database query for a specific column.
- * Handles string, boolean, and null values with appropriate SQL operations.
- * Supports quote stripping and handles different comparison operators.
- *
- * @template T - The result type for the query builder
- * @param column - The database column name to query
- * @param expression - The literal expression containing the value and quote information
- * @param operator - The comparison operator token
- * @param query - The database query builder to modify
- * @param _attributesToColumns - Mapping of model attributes to database columns (unused)
- * @param _primaryKey - The primary key column name (unused)
- * @param _tableName - The table name (unused)
- * @param allowedColumns - Optional array of allowed column names for filtering
- */
-export declare const applyLuceneLiteralExpression: (column: string, expression: LiteralExpressionToken, operator: ComparisonOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract, _attributesToColumns: ModelKeysContract, _primaryKey: string, _tableName: string, _allowedColumns?: string[] | undefined) => void;
-/**
- * Applies a range expression to a database query for a specific column.
- * Converts Lucene range syntax to SQL BETWEEN operations with proper inclusive/exclusive handling.
- *
- * @template T - The result type for the query builder
- * @param column - The database column name to query
- * @param expression - The range expression containing min/max values and inclusivity flags
- * @param operator - The comparison operator token
- * @param query - The database query builder to modify
- * @param _attributesToColumns - Mapping of model attributes to database columns (unused)
- * @param _primaryKey - The primary key column name (unused)
- * @param _tableName - The table name (unused)
- * @param allowedColumns - Optional array of allowed column names for filtering
- */
-export declare const applyLuceneRangeExpression: (column: string, expression: RangeExpressionToken, operator: ComparisonOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract, _attributesToColumns: ModelKeysContract, _primaryKey: string, _tableName: string, _allowedColumns?: string[] | undefined) => void;
-/**
- * Applies a regex expression to a database query for a specific column.
- * Converts regex patterns to SQL LIKE patterns with proper escaping.
- * Transforms * to % and ? to _ for SQL pattern matching.
- *
- * @template T - The result type for the query builder
- * @param column - The database column name to query
- * @param expression - The regex expression containing the pattern
- * @param operator - The comparison operator token
- * @param query - The database query builder to modify
- * @param _attributesToColumns - Mapping of model attributes to database columns (unused)
- * @param _primaryKey - The primary key column name (unused)
- * @param _tableName - The table name (unused)
- * @param allowedColumns - Optional array of allowed column names for filtering
- */
-export declare const applyLuceneRegexExpression: (column: string, expression: RegexExpressionToken, operator: ComparisonOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract, _attributesToColumns: ModelKeysContract, _primaryKey: string, _tableName: string, _allowedColumns?: string[] | undefined) => void;
-/**
- * Applies an implicit field AST node to a database query.
- * Implicit fields use the primary key column when no specific field is specified.
- *
- * @template T - The result type for the query builder
- * @param _field - The implicit field token (unused)
- * @param expression - The expression to apply to the primary key column
- * @param operator - The comparison operator token
- * @param query - The database query builder to modify
- * @param attributesToColumns - Mapping of model attributes to database columns
- * @param primaryKey - The primary key column name to use for implicit fields
- * @param tableName - The table name
- * @param allowedColumns - Optional array of allowed column names for filtering
- */
-export declare const applyLuceneImplicitFieldAst: (_field: ImplicitFieldToken, expression: ExpressionToken, operator: ComparisonOperatorToken | undefined, query: LuceneFilteredDatabaseQueryBuilderContract, attributesToColumns: ModelKeysContract, primaryKey: string, tableName: string, allowedColumns?: string[] | undefined) => void;
-/**
- * Applies a field AST node to a database query.
- * Maps the field name to the corresponding database column and applies the expression.
- *
- * @template T - The result type for the query builder
- * @param field - The field token containing the field name
- * @param expression - The expression to apply to the mapped column
- * @param operator - The comparison operator token
- * @param query - The database query builder to modify
- * @param attributesToColumns - Mapping of model attributes to database columns
- * @param primaryKey - The primary key column name
- * @param tableName - The table name
- * @param allowedColumns - Optional array of allowed column names for filtering
- */
-export declare const applyLuceneFieldAst: (field: FieldToken, expression: ExpressionToken, operator: ComparisonOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract, attributesToColumns: ModelKeysContract, primaryKey: string, tableName: string, allowedColumns?: string[] | undefined) => void;
-/**
- * Applies a tag AST node to a database query.
- * Tags represent field:expression pairs in Lucene syntax.
- * Delegates to either implicit field or explicit field handlers based on the field type.
- *
- * @template T - The result type for the query builder
- * @param ast - The tag AST node containing field, expression, and operator
- * @param query - The database query builder to modify
- * @param attributesToColumns - Mapping of model attributes to database columns
- * @param primaryKey - The primary key column name
- * @param tableName - The table name
- * @param allowedColumns - Optional array of allowed column names for filtering
- */
-export declare const applyLuceneTagAst: (ast: TagToken, query: LuceneFilteredDatabaseQueryBuilderContract, attributesToColumns: ModelKeysContract, primaryKey: string, tableName: string, allowedColumns?: string[] | undefined) => void;
-/**
- * Applies a unary operator AST node to a database query.
- * Handles NOT and negation (-) operators by wrapping the operand in a WHERE NOT clause.
- *
- * @template T - The result type for the query builder
- * @param ast - The unary operator AST node containing operator and operand
- * @param query - The database query builder to modify
- * @param attributesToColumns - Mapping of model attributes to database columns
- * @param primaryKey - The primary key column name
- * @param tableName - The table name
- * @param allowedColumns - Optional array of allowed column names for filtering
- */
-export declare const applyLuceneUnaryOperatorAst: (ast: UnaryOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract, attributesToColumns: ModelKeysContract, primaryKey: string, tableName: string, allowedColumns?: string[] | undefined) => void;
-/**
- * Applies any Lucene AST node to a database query.
- * This is the main dispatcher function that routes different AST node types
- * to their appropriate handler functions.
- *
- * @template T - The result type for the query builder
- * @param ast - The AST node to apply
- * @param query - The database query builder to modify
- * @param attributesToColumns - Mapping of model attributes to database columns
- * @param primaryKey - The primary key column name
- * @param tableName - The table name
- * @param allowedColumns - Optional array of allowed column names for filtering
- * @param throwOnInvalidType - Whether to throw an error for unrecognized AST node types
- */
-export declare const applyLuceneAst: (ast: ParserAst, query: LuceneFilteredDatabaseQueryBuilderContract, attributesToColumns: ModelKeysContract, primaryKey: string, tableName: string, allowedColumns: string[] | undefined, throwOnInvalidType?: boolean) => void;
+export declare class LuceneLucidQueryBuilder {
+    #private;
+    constructor(connection: QueryClientContract, query: LuceneFilteredDatabaseQueryBuilderContract, attributesToColumns: ModelKeysContract, primaryKey: string, tableName: string, allowedColumns?: string[] | undefined, model?: LucidModel | undefined);
+    applyLuceneAst(ast: ParserAst, query: LuceneFilteredDatabaseQueryBuilderContract, throwOnInvalidType?: boolean): void;
+    applyLuceneEmptyExpressionAst(_ast: EmptyExpression, _query: LuceneFilteredDatabaseQueryBuilderContract): void;
+    applyLuceneLogicalExpressionAst(ast: LogicalExpressionToken, query: LuceneFilteredDatabaseQueryBuilderContract): void;
+    applyLuceneParenthesizedExpressionAst(ast: ParenthesizedExpressionToken, query: LuceneFilteredDatabaseQueryBuilderContract): void;
+    applyLuceneUnaryOperatorAst(ast: UnaryOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract): void;
+    applyLuceneTagAst(ast: TagToken, query: LuceneFilteredDatabaseQueryBuilderContract): void;
+    applyLuceneImplicitFieldAst(_field: ImplicitFieldToken, expression: ExpressionToken, operator: ComparisonOperatorToken | undefined, query: LuceneFilteredDatabaseQueryBuilderContract): void;
+    applyLuceneFieldAst(field: FieldToken, expression: ExpressionToken, operator: ComparisonOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract, forModel?: LucidModel | undefined): void;
+    applyLuceneRelatedFieldAst(relationship: string, relatedProperty: string, expression: ExpressionToken, operator: ComparisonOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract, forModel?: LucidModel | undefined): void;
+    applyLuceneEmptyExpression(column: string, _expression: EmptyExpression, operator: ComparisonOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract): void;
+    applyLuceneLiteralExpression(column: string, expression: LiteralExpressionToken, operator: ComparisonOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract): void;
+    applyLuceneRangeExpression(column: string, expression: RangeExpressionToken, operator: ComparisonOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract): void;
+    applyLuceneRegexExpression(column: string, expression: RegexExpressionToken, operator: ComparisonOperatorToken, query: LuceneFilteredDatabaseQueryBuilderContract): void;
+    static get(luceneQuery: string, connection: QueryClientContract, attributesToColumns: ModelKeysContract, primaryKey: string, tableName: string, allowedColumns?: string[] | undefined, model?: LucidModel | undefined): LuceneFilteredDatabaseQueryBuilderContract;
+}
 /**
  * Converts a Lucene query string to a Lucid database query builder.
  * Parses the Lucene syntax and applies the resulting AST to generate SQL conditions.
@@ -193,9 +38,10 @@ export declare const applyLuceneAst: (ast: ParserAst, query: LuceneFilteredDatab
  * @param primaryKey - The primary key column name for implicit field queries
  * @param tableName - The database table name to query
  * @param allowedColumns - Optional array of allowed column names for security filtering
+ * @param model - Optional The lucid model which the query is being built for. When passed, allows relationship-based filtration.
  * @returns A database query builder with the Lucene conditions applied
  * @throws {E_LUCENE_SYNTAX_EXCEPTION} When the Lucene query has syntax errors
  * @throws {E_LUCENE_UNEXPECTED_EXCEPTION} When an unexpected error occurs during parsing
  * @throws {E_LUCENE_INVALID_TYPE} When an unrecognized AST node type is encountered
  */
-export declare const luceneToLucid: (luceneQuery: string, connection: QueryClientContract, attributesToColumns: ModelKeysContract, primaryKey: string, tableName: string, allowedColumns?: string[] | undefined) => LuceneFilteredDatabaseQueryBuilderContract;
+export declare const luceneToLucid: (luceneQuery: string, connection: QueryClientContract, attributesToColumns: ModelKeysContract, primaryKey: string, tableName: string, allowedColumns?: string[] | undefined, model?: LucidModel | undefined) => LuceneFilteredDatabaseQueryBuilderContract;

package/private/mixin.d.ts

@@ -6,7 +6,7 @@ import type { EventMap, Key, Listener } from '@nhtio/tiny-typed-emitter';
 import type { NormalizeConstructor } from '@adonisjs/core/types/helpers';
 import type { DatabaseQueryBuilderContract } from '@adonisjs/lucid/types/querybuilder';
 import type { LucidModel } from '@adonisjs/lucid/types/model';
-import type { ExternalDocumentationObject, PromiseAble, ResourcefulColumnDefinition, ResourcefulComputedAccessorDefinition, ResourcefulDataType, ResourcefulGeneralAccessControlFilter, ResourcefulModelOpenApiSchema, ResourcefulPropertySchema, ResourcefulRelationshipDefinition, ResourcefulResourceAccessControlFilter, ResourcefulModelSerializableAttributes } from '@nhtio/lucid-resourceful/types';
+import type { ExternalDocumentationObject, PromiseAble, ResourcefulColumnDefinition, ResourcefulComputedAccessorDefinition, ResourcefulDataType, ResourcefulGeneralAccessControlFilter, ResourcefulModelOpenApiSchema, ResourcefulPropertySchema, ResourcefulRelationshipDefinition, ResourcefulResourceAccessControlFilter } from '@nhtio/lucid-resourceful/types';
 /**
  * Result object returned by the resourceful index/list operation.
  *
@@ -280,10 +280,9 @@ export interface ResourcefulModel extends LucidModel {
      * );
      * ```
      */
-    $onResourcefulIndex<SelectedFields extends Array<keyof ResourcefulModelSerializableAttributes<InstanceType<LucidModel>>>, SelectedSingleField extends keyof ResourcefulModelSerializableAttributes<InstanceType<LucidModel>>, ReturnType = Pick<ResourcefulModelSerializableAttributes<InstanceType<LucidModel>>, SelectedFields[number]>>(filter: string | null | undefined, page: number, perPage: number, fields: SelectedFields | SelectedSingleField | null | undefined, sort: Array<[
-        Extract<keyof ResourcefulModelSerializableAttributes<InstanceType<LucidModel>>, string>,
-        'asc' | 'desc'
-    ]> | null | undefined, ctx: HttpContext, app: ApplicationService, hooks?: ResourcefulScopeHooks): Promise<ResourcefulIndexResult<ReturnType>>;
+    $onResourcefulIndex(filter: string | null | undefined, page: number, perPage: number, fields: string | string[] | null | undefined, sort: Array<[string, 'asc' | 'desc']> | null | undefined, ctx: HttpContext, app: ApplicationService, hooks?: ResourcefulScopeHooks): Promise<ResourcefulIndexResult<{
+        [key: string]: any;
+    }>>;
     /**
      * Retrieves a single model record by its unique identifier with access control.
      *
@@ -315,6 +314,64 @@ export interface ResourcefulModel extends LucidModel {
      * ```
      */
     $onResourcefulRead(uid: number, ctx: HttpContext, app: ApplicationService, hooks?: ResourcefulScopeHooks): Promise<any>;
+    /**
+     * Loads a specific relationship for a model record with pagination, filtering, and access control.
+     *
+     * This method provides paginated relationship loading by leveraging the related model's
+     * $onResourcefulIndex method with automatically generated relationship constraints.
+     * It supports full filtering, sorting, and pagination capabilities while maintaining
+     * proper access control and scoping.
+     *
+     * @param uid - The unique identifier of the parent record
+     * @param relationshipKey - The name of the relationship property to load
+     * @param filter - Lucene-style query string for filtering related records
+     * @param page - The page number for pagination (must be ≥ 1)
+     * @param perPage - Number of records per page (must be ≥ 1 and ≤ 100)
+     * @param fields - Array of field names to include in the response from the related model
+     * @param sort - Array of sort criteria as [field, direction] tuples
+     * @param ctx - HTTP context containing request information and authentication
+     * @param app - Application service instance for accessing app-level services
+     * @param hooks - Optional array of additional query scope callbacks
+     *
+     * @returns Promise resolving to paginated relationship results
+     *
+     * @throws {E_MISSING_PRIMARY_KEY_EXCEPTION} When the model has no identifiable primary key
+     * @throws {E_INVALID_RELATIONSHIP_EXCEPTION} When the specified relationship doesn't exist
+     * @throws {E_FORBIDDEN} When access is denied by model-level or field-level ACL filters
+     * @throws {E_INVALID_RESOUREFUL_INDEX_REQUEST_EXCEPTION} When input validation fails
+     *
+     * @example
+     * ```typescript
+     * // Load user's posts with filtering and pagination
+     * const userPosts = await Post.$onResourcefulReadRelationship(
+     *   123,                    // user ID
+     *   'posts',               // relationship name
+     *   'status:published',    // filter
+     *   1,                     // page
+     *   10,                    // perPage
+     *   ['id', 'title'],       // fields
+     *   [['createdAt', 'desc']], // sort
+     *   ctx,
+     *   app
+     * );
+     *
+     * // Load user's skills (many-to-many)
+     * const userSkills = await Skill.$onResourcefulReadRelationship(
+     *   123,
+     *   'skills',
+     *   null,  // no filter
+     *   1,
+     *   50,
+     *   null,  // all fields
+     *   null,  // default sort
+     *   ctx,
+     *   app
+     * );
+     * ```
+     */
+    $onResourcefulReadRelationship(uid: any, relationshipKey: string, filter: string | null | undefined, page: number, perPage: number, fields: string | string[] | null | undefined, sort: Array<[string, 'asc' | 'desc']> | null | undefined, ctx: HttpContext, app: ApplicationService, hooks?: ResourcefulScopeHooks): Promise<ResourcefulIndexResult<{
+        [key: string]: any;
+    }>>;
     /**
      * Creates a new model record with payload validation and access control.
      *
@@ -417,6 +474,12 @@ export interface ResourcefulModel extends LucidModel {
      * ```
      */
     $onResourcefulDelete(uid: number, ctx: HttpContext, app: ApplicationService, hooks?: ResourcefulScopeHooks): Promise<void>;
+    $onResourcefulBulkUpdate(filter: string | null | undefined, payload: any, ctx: HttpContext, app: ApplicationService, hooks?: Partial<ResourcefulHooks>): Promise<{
+        [key: string]: any | Error;
+    } | Error>;
+    $onResourcefulBulkUpdateByUid(uids: (number | string)[], payload: any, ctx: HttpContext, app: ApplicationService, hooks?: Partial<ResourcefulHooks>): Promise<{
+        [key: string]: any | Error;
+    }>;
     /**
      * Generates an OpenAPI schema object for this model with context-aware field filtering.
      *

package/private/services/open_api_schema_service.d.ts

@@ -0,0 +1,111 @@
+import type { ResourcefulModel } from '../mixin';
+import type { ResourcefulModelColumnMetaSchema, ResourcefulModelComputedAccessorMetaSchema, ResourcefulModelRelationshipMetaSchema, ResourcefulModelMetaSchema, ResourcefulModelOpenApiSchema, ResourcefulModelOpenApiRelatedSchema } from '../types';
+/**
+ * Service class for generating OpenAPI schema objects from resourceful model metadata.
+ *
+ * This service encapsulates all OpenAPI-related functionality that was previously
+ * embedded in the resourceful mixin, providing better code organization and
+ * easier testing. It handles the extraction of data type information from
+ * resourceful data types and generates proper OpenAPI schema objects.
+ *
+ * @example
+ * ```typescript
+ * const service = new OpenApiSchemaService()
+ * const schema = await service.generateModelSchema(model, ctx, app)
+ * ```
+ */
+export declare class OpenApiSchemaService {
+    #private;
+    /**
+     * Generates a complete OpenAPI schema object for a resourceful model.
+     *
+     * This method creates a comprehensive OpenAPI v3 schema representation of the model
+     * by processing the provided metadata schema. The metadata should already have
+     * field-level access control permissions evaluated for the given request context.
+     *
+     * @param resourcefulModelMetaSchema - The resourceful model metadata with ACL filtering applied
+     * @returns Complete OpenAPI schema object
+     *
+     * @example
+     * ```typescript
+     * const service = new OpenApiSchemaService()
+     * const schema = service.generateModelSchema(metaSchema)
+     * // Returns complete OpenAPI schema with accessible fields only
+     * ```
+     */
+    generateModelSchema(operation: "read" | "write" | undefined, resourcefulModelMetaSchema: ResourcefulModelMetaSchema, model?: ResourcefulModel): ResourcefulModelOpenApiSchema;
+    /**
+     * Generates OpenAPI schema for a column property.
+     *
+     * This method converts resourceful column metadata into an OpenAPI schema object,
+     * properly extracting data type information and preserving all existing schema
+     * properties such as validation constraints, nullability, and access modifiers.
+     *
+     * @param propertyKey - The name of the column property
+     * @param propertyMeta - The resourceful metadata for the column
+     * @returns OpenAPI schema object for the column
+     *
+     * @example
+     * ```typescript
+     * const service = new OpenApiSchemaService()
+     * const schema = service.generateColumnSchema('name', columnMeta)
+     * // Returns: { type: 'string', minLength: 1, maxLength: 100, ... }
+     * ```
+     */
+    generateColumnSchema(propertyKey: string, propertyMeta: ResourcefulModelColumnMetaSchema): ResourcefulModelOpenApiSchema;
+    /**
+     * Generates OpenAPI schema for a computed accessor property.
+     *
+     * This method converts resourceful computed accessor metadata into an OpenAPI
+     * schema object, applying the same data type extraction improvements as column
+     * schema generation while maintaining all existing functionality.
+     *
+     * @param propertyKey - The name of the computed accessor property
+     * @param propertyMeta - The resourceful metadata for the computed accessor
+     * @returns OpenAPI schema object for the computed accessor
+     *
+     * @example
+     * ```typescript
+     * const service = new OpenApiSchemaService()
+     * const schema = service.generateComputedAccessorSchema('fullName', accessorMeta)
+     * // Returns: { type: 'string', readOnly: true, ... }
+     * ```
+     */
+    generateComputedAccessorSchema(propertyKey: string, propertyMeta: ResourcefulModelComputedAccessorMetaSchema): ResourcefulModelOpenApiSchema;
+    /**
+     * Generates OpenAPI schema for a relationship property.
+     *
+     * This method converts resourceful relationship metadata into an OpenAPI
+     * reference object, preserving existing relationship reference generation
+     * logic and ensuring proper handling of related model references.
+     *
+     * @param propertyKey - The name of the relationship property
+     * @param propertyMeta - The resourceful metadata for the relationship
+     * @returns OpenAPI reference object for the relationship, or undefined if not applicable
+     *
+     * @example
+     * ```typescript
+     * const service = new OpenApiSchemaService()
+     * const schema = service.generateRelationshipSchema('user', relationshipMeta)
+     * // Returns: { $ref: '#/components/schemas/User' }
+     * ```
+     */
+    generateRelationshipSchema(_propertyKey: string, propertyMeta: ResourcefulModelRelationshipMetaSchema): ResourcefulModelOpenApiRelatedSchema | undefined;
+    /**
+     * Extracts default value from property metadata using Joi description.
+     *
+     * This protected method provides access to the default value extraction logic
+     * that was previously part of the mixin. It examines the Joi validator
+     * description to find default values specified in the schema.
+     *
+     * @param propertyMeta - The resourceful metadata containing the validator
+     * @returns The default value if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const service = new OpenApiSchemaService()
+     * const defaultValue = service.getDefaultValueFromPropertyMeta(propertyMeta)
+     * ```
+     */
+    protected getDefaultValueFromPropertyMeta(propertyMeta: ResourcefulModelColumnMetaSchema | ResourcefulModelComputedAccessorMetaSchema): unknown | undefined;
+}

package/private/type_guards.d.ts

@@ -1,6 +1,7 @@
 import { DateTime } from 'luxon';
 import type { LucidBinaryValue } from './types';
 import type { ResourcefulModel } from './mixin';
+import type { ResourcefulStringType, ResourcefulDateType, ResourcefulDateTimeType, ResourcefulBinaryType, ResourcefulNumberType, ResourcefulIntegerType, ResourcefulBigintType, ResourcefulUnsignedIntegerType, ResourcefulBooleanType, ResourcefulObjectType, ResourcefulArrayType } from '@nhtio/lucid-resourceful/definitions';
 /**
  * Type guard to check if a value is a Luxon DateTime instance
  * @param value - The value to check
@@ -40,3 +41,64 @@ export declare const isInstanceOf: <T>(value: unknown, type: string, ctor?: new
  * @returns True if the value is a ResourcefulModel, false otherwise
  */
 export declare const isResourcefulModel: (value: unknown) => value is ResourcefulModel;
+export declare const isResourcefulStringType: (value: unknown) => value is ResourcefulStringType;
+/**
+ * Type guard to check if a value is a ResourcefulDateType
+ * @param value - The value to check
+ * @returns True if the value is a ResourcefulDateType, false otherwise
+ */
+export declare const isResourcefulDateType: (value: unknown) => value is ResourcefulDateType;
+/**
+ * Type guard to check if a value is a ResourcefulDateTimeType
+ * @param value - The value to check
+ * @returns True if the value is a ResourcefulDateTimeType, false otherwise
+ */
+export declare const isResourcefulDateTimeType: (value: unknown) => value is ResourcefulDateTimeType;
+/**
+ * Type guard to check if a value is a ResourcefulBinaryType
+ * @param value - The value to check
+ * @returns True if the value is a ResourcefulBinaryType, false otherwise
+ */
+export declare const isResourcefulBinaryType: (value: unknown) => value is ResourcefulBinaryType;
+/**
+ * Type guard to check if a value is a ResourcefulNumberType
+ * @param value - The value to check
+ * @returns True if the value is a ResourcefulNumberType, false otherwise
+ */
+export declare const isResourcefulNumberType: (value: unknown) => value is ResourcefulNumberType;
+/**
+ * Type guard to check if a value is a ResourcefulIntegerType
+ * @param value - The value to check
+ * @returns True if the value is a ResourcefulIntegerType, false otherwise
+ */
+export declare const isResourcefulIntegerType: (value: unknown) => value is ResourcefulIntegerType;
+/**
+ * Type guard to check if a value is a ResourcefulBigintType
+ * @param value - The value to check
+ * @returns True if the value is a ResourcefulBigintType, false otherwise
+ */
+export declare const isResourcefulBigintType: (value: unknown) => value is ResourcefulBigintType;
+/**
+ * Type guard to check if a value is a ResourcefulUnsignedIntegerType
+ * @param value - The value to check
+ * @returns True if the value is a ResourcefulUnsignedIntegerType, false otherwise
+ */
+export declare const isResourcefulUnsignedIntegerType: (value: unknown) => value is ResourcefulUnsignedIntegerType;
+/**
+ * Type guard to check if a value is a ResourcefulBooleanType
+ * @param value - The value to check
+ * @returns True if the value is a ResourcefulBooleanType, false otherwise
+ */
+export declare const isResourcefulBooleanType: (value: unknown) => value is ResourcefulBooleanType;
+/**
+ * Type guard to check if a value is a ResourcefulObjectType
+ * @param value - The value to check
+ * @returns True if the value is a ResourcefulObjectType, false otherwise
+ */
+export declare const isResourcefulObjectType: (value: unknown) => value is ResourcefulObjectType;
+/**
+ * Type guard to check if a value is a ResourcefulArrayType
+ * @param value - The value to check
+ * @returns True if the value is a ResourcefulArrayType, false otherwise
+ */
+export declare const isResourcefulArrayType: (value: unknown) => value is ResourcefulArrayType;

package/private/types.d.ts

@@ -1,4 +1,4 @@
-import { CustomConsumeFunction, CustomPrepareFunction } from '@/private/prepare_consume_chain_builder.ts';
+import { CustomConsumeFunction, CustomPrepareFunction } from '@/private/prepare_consume_chain_builder';
 import type { OpenAPIV3 } from 'openapi-types';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { ApplicationService } from '@adonisjs/core/types';

package/private/utils.d.ts

@@ -8,7 +8,31 @@ export declare const isString: (value: unknown) => value is string;
  * Checks if a value is a function
  */
 export declare const isFunction: (value: unknown) => value is Function;
+/**
+ * Type guard to check if a value is an object.
+ *
+ * @param value - The value to check
+ * @returns True if the value is an object, false otherwise
+ */
+export declare const isObject: (value: unknown) => value is Record<string, any>;
 /**
  * Prepares and returns fields in a consistent format based on the input type and primary key.
  */
 export declare const prepareFields: <T>(fields: unknown, primaryKey: string) => T;
+/**
+ * Strips undefined values from an object, returning a new object with only defined values.
+ *
+ * @param obj - The object to strip undefined values from
+ * @returns A new object with undefined values removed
+ */
+export declare const stripUndefinedValuesFromObject: <T extends Record<string, any>>(obj: T) => T;
+/**
+ * Formats a syntax error message for a specific line and column in a source string.
+ *
+ * @param source - The source string to search for the error
+ * @param line - The line number where the error occurred (1-based)
+ * @param column - The column number where the error occurred (1-based)
+ * @param offset - The character offset where the error occurred (0-based)
+ * @returns A formatted error message
+ */
+export declare const formatSyntaxError: (source: string, line: number, column: number, offset: number) => string;

package/utils.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const decorator_utils = require("./decorator_utils-U_rZo8tv.cjs");
+const decorator_utils = require("./decorator_utils-DSvYjLYD.cjs");
 const casters = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
   castValueAsArray: decorator_utils.castValueAsArray,

package/utils.mjs

@@ -1,5 +1,5 @@
-import { c as castValueAsArray, a as castValueAsBigint, b as castValueAsBinary, d as castValueAsBoolean, e as castValueAsDate, f as castValueAsDateTime, g as castValueAsInteger, h as castValueAsNumber, i as castValueAsObject, j as castValueAsString, k as castValueAsUnsignedInt, p as prepareArray, l as prepareBigint, m as prepareBinary, n as prepareBoolean, o as prepareDate, q as prepareDateTime, r as prepareInteger, s as prepareNumber, t as prepareObject, u as prepareString, v as prepareUnsignedint, w as consumeArray, x as consumeBigint, y as consumeBinary, z as consumeBoolean, A as consumeDate, B as consumeDateTime, C as consumeInteger, D as consumeNumber, E as consumeObject, F as consumeString, G as consumeUnsignedint } from "./decorator_utils-YSb1EGJ6.js";
-import { H } from "./decorator_utils-YSb1EGJ6.js";
+import { c as castValueAsArray, a as castValueAsBigint, b as castValueAsBinary, d as castValueAsBoolean, e as castValueAsDate, f as castValueAsDateTime, g as castValueAsInteger, h as castValueAsNumber, i as castValueAsObject, j as castValueAsString, k as castValueAsUnsignedInt, p as prepareArray, l as prepareBigint, m as prepareBinary, n as prepareBoolean, o as prepareDate, q as prepareDateTime, r as prepareInteger, s as prepareNumber, t as prepareObject, u as prepareString, v as prepareUnsignedint, w as consumeArray, x as consumeBigint, y as consumeBinary, z as consumeBoolean, A as consumeDate, B as consumeDateTime, C as consumeInteger, D as consumeNumber, E as consumeObject, F as consumeString, G as consumeUnsignedint } from "./decorator_utils-gyymixlk.js";
+import { H } from "./decorator_utils-gyymixlk.js";
 const casters = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
   castValueAsArray,