@nhtio/lucid-resourceful 0.1.0-master-0588a748

package/private/mixin.d.ts

@@ -0,0 +1,563 @@
+import type { BaseModel } from '@adonisjs/lucid/orm';
+import type { HttpContext } from '@adonisjs/core/http';
+import type { ApplicationService } from '@adonisjs/core/types';
+import type { AnySchema, ObjectSchema } from 'joi';
+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';
+/**
+ * Result object returned by the resourceful index/list operation.
+ *
+ * Contains paginated records along with metadata about the query execution
+ * and pagination state. The records are filtered according to field-level
+ * access control and only contain the requested fields.
+ *
+ * @template ReturnType - The shape of records after field selection and ACL filtering
+ */
+export interface ResourcefulIndexResult<ReturnType = any> {
+    /** Array of records with only the requested and accessible fields */
+    records: Array<Partial<ReturnType>>;
+    /** Total number of records matching the filter (before pagination) */
+    total: number;
+    /** The current page number (1-based) */
+    page: number;
+    /** Number of records per page */
+    perPage: number;
+    /** SQL query string used for counting total records */
+    countQuery: string;
+    /** SQL query string used for fetching the paginated records */
+    recordsQuery: string;
+}
+/**
+ * Function type for generating payload validation schemas based on request context.
+ *
+ * These functions are called during create and update operations to generate
+ * context-specific validation schemas using Joi. They provide the core model-level
+ * validation that applies regardless of request-specific hooks.
+ *
+ * @param ctx - HTTP context containing request information and authentication
+ * @param app - Application service instance for accessing app-level services
+ * @returns Promise resolving to a Joi schema for validating the request payload
+ */
+export interface ResourcefulPayloadValidatorGetter {
+    (ctx: HttpContext, app: ApplicationService): PromiseAble<AnySchema>;
+}
+/**
+ * Function type for generating request-specific payload validation schemas.
+ *
+ * These functions are provided via hooks during create and update operations
+ * to add additional validation constraints beyond the base model validation.
+ * They enable request-specific validation logic based on context.
+ *
+ * @param ctx - HTTP context containing request information and authentication
+ * @param app - Application service instance for accessing app-level services
+ * @returns Promise resolving to a Joi ObjectSchema for additional validation, or null to skip
+ */
+export interface ResourcefulPayloadSchemaGetter {
+    (ctx: HttpContext, app: ApplicationService): PromiseAble<ObjectSchema | null>;
+}
+/**
+ * Function type for applying query-level scoping to database queries.
+ *
+ * These callbacks are applied to queries during CRUD operations to enforce
+ * data access boundaries based on request context. They modify the query
+ * in-place by adding WHERE clauses, JOINs, or other constraints.
+ *
+ * @param ctx - HTTP context containing request information and authentication
+ * @param app - Application service instance for accessing app-level services
+ * @param query - Database query builder to modify with scoping constraints
+ * @returns Promise that resolves when the query has been modified
+ */
+export interface ResourcefulQueryScopeCallback {
+    (ctx: HttpContext, app: ApplicationService, query: DatabaseQueryBuilderContract): PromiseAble<void>;
+}
+/**
+ * Array of query scope callback functions.
+ *
+ * Used for operations that need to apply query-level scoping (index, read, delete).
+ * Callbacks are applied in sequence to build up the complete set of access constraints.
+ */
+export type ResourcefulScopeHooks = ResourcefulQueryScopeCallback[];
+/**
+ * Array of payload validation schema getter functions.
+ *
+ * Used for operations that accept request payloads (create, update).
+ * Each function can return additional validation constraints based on request context.
+ */
+export type ResourcefulValidationHooks = ResourcefulPayloadSchemaGetter[];
+/**
+ * Combined hook interface providing both query scoping and payload validation.
+ *
+ * Used by the update operation which needs both query scoping (to find the record)
+ * and payload validation (to validate the update data).
+ */
+export interface ResourcefulHooks {
+    /** Query scope callbacks for constraining database queries */
+    queryScopeCallbacks: ResourcefulScopeHooks;
+    /** Payload validation schema getters for additional validation */
+    payloadValidationSchemas: ResourcefulValidationHooks;
+}
+export type ResourcefulMixinEventMap<Model extends LucidModel = LucidModel, ModelInstance = InstanceType<Model>> = EventMap<{
+    'acl:error': [unknown, HttpContext, ApplicationService, ModelInstance | undefined];
+    'validation:scope:error': [unknown, HttpContext, ApplicationService, string, ResourcefulDataType];
+}>;
+/**
+ * Enhanced Lucid model interface providing resourceful CRUD functionality.
+ *
+ * This interface extends the base LucidModel with metadata-driven CRUD operations,
+ * field-level access control, query scoping, OpenAPI schema generation, and event
+ * handling capabilities. Models implementing this interface gain static methods
+ * for handling HTTP requests with built-in validation, pagination, filtering,
+ * and comprehensive security features.
+ *
+ * The interface defines both metadata storage properties and operational methods
+ * that work together to provide a complete resourceful API layer on top of
+ * AdonisJS Lucid ORM models.
+ *
+ * @extends LucidModel
+ *
+ * @example
+ * ```typescript
+ * import { BaseModel, column } from '@ioc:Adonis/Lucid/Orm'
+ * import { withResourceful, resourceful } from 'lucid-resourceful'
+ *
+ * class User extends withResourceful()(BaseModel) implements ResourcefulModel {
+ *   @column({ isPrimary: true })
+ *   @resourceful({ type: 'number', nullable: false })
+ *   public id: number
+ *
+ *   @column()
+ *   @resourceful({ type: 'string', nullable: false })
+ *   public name: string
+ *
+ *   // Automatically gains all ResourcefulModel methods
+ *   // User.$onResourcefulIndex, User.$onResourcefulRead, etc.
+ * }
+ * ```
+ */
+export interface ResourcefulModel extends LucidModel {
+    /** The display name for this model used in API documentation and error messages */
+    $resourcefulName: string;
+    /** Optional description for OpenAPI schema documentation */
+    $resourcefulMetaDescription?: string;
+    /** Optional external documentation reference for OpenAPI schema */
+    $resourcefulMetaExternalDocs?: ExternalDocumentationObject;
+    /** Optional example value for OpenAPI schema documentation */
+    $resourcefulMetaExample?: string;
+    /** Map of column property names to their resourceful metadata definitions */
+    $resourcefulColumns: Map<string, ResourcefulColumnDefinition<ResourcefulPropertySchema>>;
+    /** Map of relationship property names to their resourceful metadata definitions */
+    $resourcefulRelationships: Map<string, ResourcefulRelationshipDefinition>;
+    /** Map of computed accessor property names to their resourceful metadata definitions */
+    $resourcefulComputedAccessors: Map<string, ResourcefulComputedAccessorDefinition<ResourcefulPropertySchema>>;
+    /** Access control filter functions organized by CRUD operation type */
+    $resourcefulAccessControlFilters: ResourcefulMixinOptions['accessControlFilters'];
+    /** Error handling strategy when ACL evaluation fails */
+    $resourcefulOnACLError: ResourcefulMixinOptions['onACLError'];
+    /** Query scope callback functions for constraining database queries */
+    $resourcefulQueryScopeCallbacks: ResourcefulMixinOptions['queryScopeCallbacks'];
+    /** Payload validation schema builder functions for create and update operations */
+    $resourcefulPayloadValidationSchemaBuilders: ResourcefulMixinOptions['payloadValidationSchemaBuilders'];
+    /**
+     * Registers an event listener for resourceful model events.
+     *
+     * This method provides a way to listen for events emitted during resourceful
+     * operations such as ACL errors or validation scope errors. Useful for logging,
+     * monitoring, or implementing custom error handling logic.
+     *
+     * @template K - The event key type from the resourceful event map
+     * @param event - The name of the event to listen for ('acl:error', 'validation:scope:error')
+     * @param listener - Function to call when the event is emitted
+     * @returns The model class for method chaining
+     *
+     * @example
+     * ```typescript
+     * User.$onResourcefulEvent('acl:error', (error, ctx, app, instance) => {
+     *   console.error('ACL error occurred:', error);
+     * });
+     * ```
+     */
+    $onResourcefulEvent<K>(event: Key<K, ResourcefulMixinEventMap<ResourcefulModel>>, listener: Listener<K, ResourcefulMixinEventMap<ResourcefulModel>>): this;
+    /**
+     * Registers a one-time event listener for resourceful model events.
+     *
+     * Similar to $onResourcefulEvent but the listener is automatically removed
+     * after being called once. Useful for handling events that should only
+     * trigger a single response.
+     *
+     * @template K - The event key type from the resourceful event map
+     * @param event - The name of the event to listen for
+     * @param listener - Function to call when the event is emitted
+     * @returns The model class for method chaining
+     *
+     * @example
+     * ```typescript
+     * User.$onceResourcefulEvent('validation:scope:error', (error, ctx, app, key, datatype) => {
+     *   console.warn('Validation scope error (one-time):', error);
+     * });
+     * ```
+     */
+    $onceResourcefulEvent<K>(event: Key<K, ResourcefulMixinEventMap<ResourcefulModel>>, listener: Listener<K, ResourcefulMixinEventMap<ResourcefulModel>>): this;
+    /**
+     * Removes an event listener for resourceful model events.
+     *
+     * Unregisters a previously registered event listener. If no listener is
+     * provided, all listeners for the specified event are removed.
+     *
+     * @template K - The event key type from the resourceful event map
+     * @param event - The name of the event to stop listening for
+     * @param listener - Optional specific listener function to remove
+     * @returns The model class for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Remove specific listener
+     * User.$offResourcefulEvent('acl:error', myErrorHandler);
+     *
+     * // Remove all listeners for an event
+     * User.$offResourcefulEvent('acl:error');
+     * ```
+     */
+    $offResourcefulEvent<K>(event: Key<K, ResourcefulMixinEventMap<ResourcefulModel>>, listener?: Listener<K, ResourcefulMixinEventMap<ResourcefulModel>>): this;
+    /**
+     * Performs paginated listing and searching of model records with comprehensive filtering.
+     *
+     * This method provides the core implementation for resourceful index/list operations,
+     * supporting pagination, field selection, access control, and Lucene query syntax for
+     * filtering. It validates all inputs, applies ACL filters, executes the query with
+     * proper field mapping between serialized names and database columns, and returns
+     * structured results with query metadata.
+     *
+     * @template SelectedFields - Array of field names that can be selected from the model's serializable attributes
+     * @template ReturnType - The resulting type after picking the selected fields from the model's serializable attributes
+     *
+     * @param filter - Lucene-style query string for filtering records (e.g., "name:john AND email:*.com").
+     *                 If null or undefined, defaults to empty string (no filtering).
+     * @param page - The page number for pagination (must be ≥ 1). Used with perPage to calculate offset.
+     * @param perPage - Number of records per page (must be ≥ 1 and ≤ 100 by default).
+     * @param fields - Array of field names to include in the response. If null, undefined, or empty,
+     *                 defaults to just the primary key field. Field names should use serialized names
+     *                 (as they appear in API responses), not database column names.
+     * @param ctx - HTTP context containing request information, authentication, and other request-scoped data.
+     * @param app - Application service instance providing access to application-level services and configuration.
+     * @param hooks - Optional array of query scope callbacks to apply additional filtering constraints.
+     *
+     * @returns Promise resolving to ResourcefulIndexResult containing:
+     *   - `records`: Array of partial record objects with only the requested fields
+     *   - `total`: Total number of records matching the filter (before pagination)
+     *   - `page`: The requested page number (echoed back)
+     *   - `perPage`: The requested per-page limit (echoed back)
+     *   - `countQuery`: SQL query string used for counting total records
+     *   - `recordsQuery`: SQL query string used for fetching the actual records
+     *
+     * @throws {E_MISSING_PRIMARY_KEY_EXCEPTION} When the model has no identifiable primary key
+     * @throws {E_FORBIDDEN} When access is denied by model-level or field-level ACL filters
+     * @throws {E_INVALID_COLUMN_ACCESS} When no fields are available for access after ACL filtering
+     * @throws {E_INVALID_RESOUREFUL_INDEX_REQUEST_EXCEPTION} When input validation fails
+     *
+     * @example
+     * ```typescript
+     * // Basic usage with pagination
+     * const result = await User.$onResourcefulIndex(
+     *   'name:john',
+     *   1,
+     *   10,
+     *   ['id', 'name', 'email'],
+     *   ctx,
+     *   app
+     * );
+     *
+     * // Complex filtering with date ranges
+     * const result = await User.$onResourcefulIndex(
+     *   'name:john AND createdAt:[2021-01-01T00:00:00Z TO 2021-12-31T23:59:59Z]',
+     *   2,
+     *   25,
+     *   ['id', 'name', 'createdAt'],
+     *   ctx,
+     *   app
+     * );
+     * ```
+     */
+    $onResourcefulIndex<SelectedFields extends Array<keyof ResourcefulModelSerializableAttributes<InstanceType<LucidModel>>>, ReturnType = Pick<ResourcefulModelSerializableAttributes<InstanceType<LucidModel>>, SelectedFields[number]>>(filter: string | null | undefined, page: number, perPage: number, fields: SelectedFields | null | undefined, ctx: HttpContext, app: ApplicationService, hooks?: ResourcefulScopeHooks): Promise<ResourcefulIndexResult<ReturnType>>;
+    /**
+     * Retrieves a single model record by its unique identifier with access control.
+     *
+     * This method implements secure record retrieval by first applying query scope callbacks
+     * to verify the record exists within the user's access scope, then fetching the full
+     * model instance for field-level ACL evaluation. Only fields that pass ACL checks
+     * are included in the response.
+     *
+     * @param uid - The unique identifier of the record to retrieve
+     * @param ctx - HTTP context containing request information and authentication
+     * @param app - Application service instance for accessing app-level services
+     * @param hooks - Optional array of query scope callbacks to apply additional filtering constraints
+     *
+     * @returns Promise resolving to the record object with only accessible fields
+     *
+     * @throws {E_MISSING_PRIMARY_KEY_EXCEPTION} When the model has no identifiable primary key
+     * @throws {E_RECORD_NOT_FOUND_EXCEPTION} When no record exists with the given ID or user lacks access
+     * @throws {E_FORBIDDEN} When access is denied by model-level or field-level ACL filters
+     *
+     * @example
+     * ```typescript
+     * // Retrieve a user by ID
+     * const user = await User.$onResourcefulRead(123, ctx, app);
+     *
+     * // With additional query scoping
+     * const user = await User.$onResourcefulRead(123, ctx, app, [
+     *   (ctx, app, query) => query.where('tenant_id', ctx.auth.user.tenantId)
+     * ]);
+     * ```
+     */
+    $onResourcefulRead(uid: number, ctx: HttpContext, app: ApplicationService, hooks?: ResourcefulScopeHooks): Promise<any>;
+    /**
+     * Creates a new model record with payload validation and access control.
+     *
+     * This method handles secure record creation by validating the request payload
+     * against both model-level and request-specific validation schemas, checking
+     * field-level write permissions, and returning the created record with appropriate
+     * field filtering applied.
+     *
+     * @param payload - The data object containing field values for the new record
+     * @param ctx - HTTP context containing request information and authentication
+     * @param app - Application service instance for accessing app-level services
+     * @param hooks - Optional array of validation schema getters for additional payload validation
+     *
+     * @returns Promise resolving to the created record with only accessible fields
+     *
+     * @throws {E_MISSING_PRIMARY_KEY_EXCEPTION} When the model has no identifiable primary key
+     * @throws {E_INVALID_PAYLOAD_EXCEPTION} When core model validation fails
+     * @throws {E_FORBIDDEN_PAYLOAD_EXCEPTION} When request-specific validation fails
+     * @throws {E_FORBIDDEN} When access is denied by model-level or field-level ACL filters
+     *
+     * @example
+     * ```typescript
+     * // Create a new user
+     * const user = await User.$onResourcefulCreate({
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * }, ctx, app);
+     *
+     * // With additional validation
+     * const user = await User.$onResourcefulCreate(payload, ctx, app, [
+     *   (ctx, app) => joi.object({ email: joi.string().domain('company.com') })
+     * ]);
+     * ```
+     */
+    $onResourcefulCreate(payload: any, ctx: HttpContext, app: ApplicationService, hooks?: ResourcefulValidationHooks): Promise<any>;
+    /**
+     * Updates an existing model record with payload validation and access control.
+     *
+     * This method implements secure record updates by first verifying the record exists
+     * and is accessible via the read operation, validating the update payload, checking
+     * field-level write permissions, and returning the updated record with appropriate
+     * field filtering applied.
+     *
+     * @param uid - The unique identifier of the record to update
+     * @param payload - The data object containing field values to update
+     * @param ctx - HTTP context containing request information and authentication
+     * @param app - Application service instance for accessing app-level services
+     * @param hooks - Optional object containing query scope callbacks and validation schema getters
+     *
+     * @returns Promise resolving to the updated record with only accessible fields
+     *
+     * @throws {E_MISSING_PRIMARY_KEY_EXCEPTION} When the model has no identifiable primary key
+     * @throws {E_RECORD_NOT_FOUND_EXCEPTION} When no record exists with the given ID or user lacks access
+     * @throws {E_INVALID_PAYLOAD_EXCEPTION} When core model validation fails
+     * @throws {E_FORBIDDEN_PAYLOAD_EXCEPTION} When request-specific validation fails
+     * @throws {E_FORBIDDEN} When access is denied by model-level or field-level ACL filters
+     *
+     * @example
+     * ```typescript
+     * // Update a user
+     * const user = await User.$onResourcefulUpdate(123, {
+     *   name: 'Jane Doe'
+     * }, ctx, app);
+     *
+     * // With additional scoping and validation
+     * const user = await User.$onResourcefulUpdate(123, payload, ctx, app, {
+     *   queryScopeCallbacks: [(ctx, app, query) => query.where('active', true)],
+     *   payloadValidationSchemas: [(ctx, app) => customValidationSchema]
+     * });
+     * ```
+     */
+    $onResourcefulUpdate(uid: number, payload: any, ctx: HttpContext, app: ApplicationService, hooks?: Partial<ResourcefulHooks>): Promise<any>;
+    /**
+     * Deletes an existing model record with access control.
+     *
+     * This method implements secure record deletion by applying query scope callbacks
+     * to verify the record exists within the user's access scope, checking delete
+     * permissions via ACL filters, and then removing the record from the database.
+     *
+     * @param uid - The unique identifier of the record to delete
+     * @param ctx - HTTP context containing request information and authentication
+     * @param app - Application service instance for accessing app-level services
+     * @param hooks - Optional array of query scope callbacks to apply additional filtering constraints
+     *
+     * @returns Promise that resolves when the record has been successfully deleted
+     *
+     * @throws {E_MISSING_PRIMARY_KEY_EXCEPTION} When the model has no identifiable primary key
+     * @throws {E_RECORD_NOT_FOUND_EXCEPTION} When no record exists with the given ID or user lacks access
+     * @throws {E_FORBIDDEN} When access is denied by model-level ACL filters
+     *
+     * @example
+     * ```typescript
+     * // Delete a user
+     * await User.$onResourcefulDelete(123, ctx, app);
+     *
+     * // With additional query scoping
+     * await User.$onResourcefulDelete(123, ctx, app, [
+     *   (ctx, app, query) => query.where('tenant_id', ctx.auth.user.tenantId)
+     * ]);
+     * ```
+     */
+    $onResourcefulDelete(uid: number, ctx: HttpContext, app: ApplicationService, hooks?: ResourcefulScopeHooks): Promise<void>;
+    /**
+     * Generates an OpenAPI schema object for this model with context-aware field filtering.
+     *
+     * This method creates a complete OpenAPI v3 schema representation of the model
+     * by evaluating field-level access control permissions for the given request context.
+     * Only fields that pass ACL checks are included in the generated schema, ensuring
+     * that API documentation accurately reflects what data is accessible to the current user.
+     *
+     * The method processes all resourceful properties (columns, computed accessors, and
+     * relationships) and converts them to their OpenAPI schema equivalents while respecting
+     * access control constraints and applying proper type mappings.
+     *
+     * @param ctx - HTTP context containing request information and authentication
+     * @param app - Application service instance for accessing app-level services
+     *
+     * @returns Promise resolving to a complete OpenAPI schema object with:
+     *   - `type`: Always 'object' for model schemas
+     *   - `title`: The model's resourceful name
+     *   - `description`: Optional model description from metadata
+     *   - `properties`: Object containing schema definitions for accessible fields
+     *   - `required`: Array of required field names (non-nullable fields)
+     *   - `externalDocs`: Optional external documentation reference
+     *   - `example`: Optional example value for the schema
+     *
+     * @example
+     * ```typescript
+     * // Generate OpenAPI schema for current user context
+     * const schema = await User.$asOpenApiSchemaObject(ctx, app);
+     *
+     * // Result structure:
+     * {
+     *   type: 'object',
+     *   title: 'User',
+     *   properties: {
+     *     id: { type: 'number', readOnly: true },
+     *     name: { type: 'string' },
+     *     email: { type: 'string', format: 'email' }
+     *   },
+     *   required: ['id', 'name', 'email']
+     * }
+     * ```
+     *
+     * @see {@link ResourcefulModelOpenApiSchema} for the complete schema structure
+     */
+    $asOpenApiSchemaObject(ctx: HttpContext, app: ApplicationService): Promise<ResourcefulModelOpenApiSchema>;
+}
+export declare const ResourcefulErrorHandlerMethod: readonly ["bubble", "pass", "fail"];
+export type ResourcefulErrorHandlerMethod = (typeof ResourcefulErrorHandlerMethod)[number];
+export declare const ResourcefulACLOperationType: readonly ["read", "write"];
+export type ResourcefulACLOperationType = (typeof ResourcefulACLOperationType)[number];
+export interface AdvancedResourcefulMixinOptions {
+    propertyEvaluationConcurrency: number;
+    aclEvaluationConcurrency: number;
+}
+export interface ResourcefulMixinOptions<Model extends LucidModel = LucidModel, ModelInstance = InstanceType<Model>> {
+    name: string;
+    readRequiredForWrite: boolean;
+    accessControlFilters: {
+        list: ResourcefulGeneralAccessControlFilter[];
+        create: ResourcefulGeneralAccessControlFilter[];
+        read: ResourcefulResourceAccessControlFilter<Model, ModelInstance>[];
+        update: ResourcefulResourceAccessControlFilter<Model, ModelInstance>[];
+        delete: ResourcefulResourceAccessControlFilter<Model, ModelInstance>[];
+    };
+    payloadValidationSchemaBuilders: {
+        create: ResourcefulPayloadValidatorGetter[];
+        update: ResourcefulPayloadValidatorGetter[];
+    };
+    onACLError: ResourcefulErrorHandlerMethod;
+    onValidationScopeError: ResourcefulErrorHandlerMethod;
+    queryScopeCallbacks: {
+        list: ResourcefulQueryScopeCallback[];
+        access: ResourcefulQueryScopeCallback[];
+    };
+    description?: string;
+    externalDocs?: ExternalDocumentationObject;
+    example?: string;
+    advanced: AdvancedResourcefulMixinOptions;
+}
+/**
+ * Creates a mixin that adds resourceful CRUD functionality to Lucid models.
+ *
+ * This function implements the mixin pattern to enhance AdonisJS Lucid models with
+ * metadata-driven CRUD operations, field-level access control, query scoping,
+ * and OpenAPI schema generation capabilities. The resulting model gains static
+ * methods for handling HTTP requests with built-in validation, pagination,
+ * filtering, and security features.
+ *
+ * The mixin validates and normalizes configuration options, creates isolated
+ * metadata maps for each model class to prevent inheritance conflicts, and
+ * establishes an event emitter for monitoring ACL and validation operations.
+ *
+ * @param options - Configuration object for customizing mixin behavior
+ * @param options.name - Display name for the model (defaults to class name)
+ * @param options.readRequiredForWrite - Whether read access is required before write operations
+ * @param options.accessControlFilters - Object containing arrays of ACL filter functions for different operations
+ * @param options.accessControlFilters.list - Filters applied during listing/search operations
+ * @param options.accessControlFilters.create - Filters applied during record creation
+ * @param options.accessControlFilters.read - Filters applied during record reading
+ * @param options.accessControlFilters.update - Filters applied during record updates
+ * @param options.accessControlFilters.delete - Filters applied during record deletion
+ * @param options.onACLError - Error handling strategy when ACL evaluation fails ('throw', 'pass', 'fail')
+ * @param options.onValidationScopeError - Error handling strategy when validation scope functions fail
+ * @param options.queryScopeCallbacks - Object containing query scope callback functions
+ * @param options.queryScopeCallbacks.list - Callbacks applied to listing/search queries
+ * @param options.queryScopeCallbacks.access - Callbacks applied to individual record access queries
+ * @param options.description - Optional description for OpenAPI documentation
+ * @param options.externalDocs - Optional external documentation reference for OpenAPI
+ * @param options.example - Optional example value for OpenAPI documentation
+ * @param options.advanced - Advanced configuration options for performance tuning
+ * @param options.advanced.propertyEvaluationConcurrency - Concurrency limit for property ACL evaluation
+ * @param options.advanced.aclEvaluationConcurrency - Concurrency limit for ACL filter evaluation
+ *
+ * @returns A mixin function that accepts a Lucid model class and returns the enhanced model
+ *
+ * @throws {E_INVALID_RESOURCEFUL_MIXIN_OPTIONS} When the provided options fail validation
+ *
+ * @example
+ * ```typescript
+ * import { BaseModel, column } from '@ioc:Adonis/Lucid/Orm'
+ * import { withResourceful, resourceful } from 'lucid-resourceful'
+ *
+ * class User extends withResourceful({
+ *   name: 'User',
+ *   readRequiredForWrite: true,
+ *   accessControlFilters: {
+ *     read: [(ctx) => ctx.auth.user?.id === ctx.params.id],
+ *     update: [(ctx) => ctx.auth.user?.isAdmin]
+ *   }
+ * })(BaseModel) {
+ *   @column({ isPrimary: true })
+ *   @resourceful({ type: 'number', nullable: false })
+ *   public id: number
+ *
+ *   @column()
+ *   @resourceful({ type: 'string', nullable: false })
+ *   public name: string
+ * }
+ *
+ * // Generated controller with CRUD operations
+ * const UserController = User.generateController()
+ * ```
+ *
+ * @see {@link ResourcefulMixinOptions} for detailed configuration options
+ * @see {@link ResourcefulModel} for the enhanced model interface
+ */
+export declare function withResourceful(options?: Partial<ResourcefulMixinOptions>): <Model extends NormalizeConstructor<typeof BaseModel>>(superclass: Model) => Model & ResourcefulModel;