@nhtio/lucid-resourceful 1.20250718.0

package/private/decorator_utils.d.ts

@@ -0,0 +1,305 @@
+import { DateTime } from 'luxon';
+import type { LucidBinaryValue, LucidPlainObject } from '@nhtio/lucid-resourceful/types';
+/**
+ * Casts an unknown value to a string
+ * @param value - The value to cast
+ * @returns The value as a string
+ * @throws E_UNCASTABLE when the value cannot be cast to a string
+ */
+export declare const castValueAsString: (value: unknown) => string;
+/**
+ * Casts an unknown value to a Luxon DateTime with enhanced string parsing
+ * @param value - The value to cast (string, number, Date, or DateTime)
+ * @returns The value as a Luxon DateTime
+ * @throws E_UNCASTABLE when the value cannot be cast to a DateTime
+ * @remarks For string values, attempts SQL format parsing first, then falls back to ISO format parsing
+ */
+export declare const castValueAsDate: (value: unknown) => DateTime;
+/**
+ * Casts an unknown value to a Luxon DateTime with enhanced error handling and string parsing
+ * @param value - The value to cast (string, number, Date, or DateTime)
+ * @returns The value as a Luxon DateTime
+ * @throws E_UNCASTABLE when the value cannot be cast to a DateTime
+ * @remarks For string values, attempts SQL format parsing first, then falls back to ISO format parsing
+ */
+export declare const castValueAsDateTime: (value: unknown) => DateTime;
+/**
+ * Casts an unknown value to a Uint8Array (binary data)
+ * @param value - The value to cast
+ * @returns The value as a Uint8Array
+ * @throws E_UNCASTABLE when the value cannot be cast to binary data
+ */
+export declare const castValueAsBinary: (value: unknown) => Uint8Array;
+/**
+ * Casts an unknown value to a number
+ * @param value - The value to cast
+ * @returns The value as a number
+ * @throws E_UNCASTABLE when the value cannot be cast to a number
+ */
+export declare const castValueAsNumber: (value: unknown) => number;
+/**
+ * Casts an unknown value to an integer
+ * @param value - The value to cast
+ * @returns The value as an integer (truncated if necessary)
+ * @throws E_UNCASTABLE when the value cannot be cast to an integer
+ */
+export declare const castValueAsInteger: (value: unknown) => number;
+/**
+ * Casts an unknown value to a bigint
+ * @param value - The value to cast
+ * @returns The value as a bigint
+ * @throws E_UNCASTABLE when the value cannot be cast to a bigint
+ */
+export declare const castValueAsBigint: (value: unknown) => bigint;
+/**
+ * Casts an unknown value to an unsigned integer
+ * @param value - The value to cast
+ * @returns The value as an unsigned integer (32-bit)
+ * @throws E_UNCASTABLE when the value cannot be cast to an unsigned integer
+ */
+export declare const castValueAsUnsignedInt: (value: unknown) => number;
+/**
+ * Casts an unknown value to a boolean
+ * @param value - The value to cast
+ * @returns The value as a boolean
+ * @throws E_UNCASTABLE when the value cannot be cast to a boolean
+ */
+export declare const castValueAsBoolean: (value: unknown) => boolean;
+/**
+ * Casts an unknown value to a plain object
+ * @param value - The value to cast
+ * @returns The value as a LucidPlainObject
+ * @throws E_UNCASTABLE when the value cannot be cast to an object
+ */
+export declare const castValueAsObject: (value: unknown) => LucidPlainObject;
+/**
+ * Casts an unknown value to an array
+ * @param value - The value to cast
+ * @returns The value as an array of unknown elements
+ * @throws E_UNCASTABLE when the value cannot be cast to an array
+ */
+export declare const castValueAsArray: (value: unknown) => Array<unknown>;
+/**
+ * Prepares a string value for database storage with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to prepare
+ * @param nullable - Whether the field can be null
+ * @returns The prepared string value or null if nullable and value is null
+ * @throws E_INVALID_PREPARED_VALUE when the value cannot be prepared
+ */
+export declare function prepareString(key: string, value: unknown, nullable: true): string | null;
+export declare function prepareString(key: string, value: unknown, nullable?: false): string;
+/**
+ * Prepares a date value for database storage with nullable support and enhanced string parsing
+ * @param key - The field name for error reporting
+ * @param value - The value to prepare
+ * @param nullable - Whether the field can be null
+ * @returns The prepared DateTime value or null if nullable and value is null
+ * @throws E_INVALID_PREPARED_VALUE when the value cannot be prepared
+ * @remarks For string values, attempts SQL format parsing first, then falls back to ISO format parsing
+ */
+export declare function prepareDate(key: string, value: unknown, nullable: true): DateTime | null;
+export declare function prepareDate(key: string, value: unknown, nullable?: false): DateTime;
+/**
+ * Prepares a datetime value for database storage with nullable support and enhanced string parsing
+ * @param key - The field name for error reporting
+ * @param value - The value to prepare
+ * @param nullable - Whether the field can be null
+ * @returns The prepared DateTime value or null if nullable and value is null
+ * @throws E_INVALID_PREPARED_VALUE when the value cannot be prepared
+ * @remarks For string values, attempts SQL format parsing first, then falls back to ISO format parsing
+ */
+export declare function prepareDateTime(key: string, value: unknown, nullable: true): DateTime | null;
+export declare function prepareDateTime(key: string, value: unknown, nullable?: false): DateTime;
+/**
+ * Prepares a binary value for database storage with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to prepare
+ * @param nullable - Whether the field can be null
+ * @returns The prepared binary value or null if nullable and value is null
+ * @throws E_INVALID_PREPARED_VALUE when the value cannot be prepared
+ */
+export declare function prepareBinary(key: string, value: unknown, nullable: true): LucidBinaryValue | null;
+export declare function prepareBinary(key: string, value: unknown, nullable?: false): LucidBinaryValue;
+/**
+ * Prepares a number value for database storage with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to prepare
+ * @param nullable - Whether the field can be null
+ * @returns The prepared number value or null if nullable and value is null
+ * @throws E_INVALID_PREPARED_VALUE when the value cannot be prepared
+ */
+export declare function prepareNumber(key: string, value: unknown, nullable: true): number | null;
+export declare function prepareNumber(key: string, value: unknown, nullable?: false): number;
+/**
+ * Prepares an integer value for database storage with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to prepare
+ * @param nullable - Whether the field can be null
+ * @returns The prepared integer value or null if nullable and value is null
+ * @throws E_INVALID_PREPARED_VALUE when the value cannot be prepared
+ */
+export declare function prepareInteger(key: string, value: unknown, nullable: true): number | null;
+export declare function prepareInteger(key: string, value: unknown, nullable?: false): number;
+/**
+ * Prepares a bigint value for database storage with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to prepare
+ * @param nullable - Whether the field can be null
+ * @returns The prepared bigint value or null if nullable and value is null
+ * @throws E_INVALID_PREPARED_VALUE when the value cannot be prepared
+ */
+export declare function prepareBigint(key: string, value: unknown, nullable: true): bigint | null;
+export declare function prepareBigint(key: string, value: unknown, nullable?: false): bigint;
+/**
+ * Prepares an unsigned integer value for database storage with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to prepare
+ * @param nullable - Whether the field can be null
+ * @returns The prepared unsigned integer value or null if nullable and value is null
+ * @throws E_INVALID_PREPARED_VALUE when the value cannot be prepared
+ */
+export declare function prepareUnsignedint(key: string, value: unknown, nullable: true): number | null;
+export declare function prepareUnsignedint(key: string, value: unknown, nullable?: false): number;
+/**
+ * Prepares a boolean value for database storage with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to prepare
+ * @param nullable - Whether the field can be null
+ * @returns The prepared boolean value or null if nullable and value is null
+ * @throws E_INVALID_PREPARED_VALUE when the value cannot be prepared
+ */
+export declare function prepareBoolean(key: string, value: unknown, nullable: true): boolean | null;
+export declare function prepareBoolean(key: string, value: unknown, nullable?: false): boolean;
+/**
+ * Prepares an object value for database storage with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to prepare
+ * @param nullable - Whether the field can be null
+ * @returns The prepared object value or null if nullable and value is null
+ * @throws E_INVALID_PREPARED_VALUE when the value cannot be prepared
+ */
+export declare function prepareObject(key: string, value: unknown, nullable: true): LucidPlainObject | null;
+export declare function prepareObject(key: string, value: unknown, nullable?: false): LucidPlainObject;
+/**
+ * Prepares an array value for database storage with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to prepare
+ * @param nullable - Whether the field can be null
+ * @returns The prepared array value or null if nullable and value is null
+ * @throws E_INVALID_PREPARED_VALUE when the value cannot be prepared
+ */
+export declare function prepareArray(key: string, value: unknown, nullable: true): Array<unknown> | null;
+export declare function prepareArray(key: string, value: unknown, nullable?: false): Array<unknown>;
+/**
+ * Consumes a string value from database results with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to consume
+ * @param nullable - Whether the field can be null
+ * @returns The consumed string value or null if nullable and value is null
+ * @throws E_INVALID_CONSUMED_VALUE when the value cannot be consumed
+ */
+export declare function consumeString(key: string, value: unknown, nullable: true): string | null;
+export declare function consumeString(key: string, value: unknown, nullable?: false): string;
+/**
+ * Consumes a date value from database results with nullable support and enhanced string parsing
+ * @param key - The field name for error reporting
+ * @param value - The value to consume
+ * @param nullable - Whether the field can be null
+ * @returns The consumed DateTime value or null if nullable and value is null
+ * @throws E_INVALID_CONSUMED_VALUE when the value cannot be consumed
+ * @remarks For string values, attempts SQL format parsing first, then falls back to ISO format parsing
+ */
+export declare function consumeDate(key: string, value: unknown, nullable: true): DateTime | null;
+export declare function consumeDate(key: string, value: unknown, nullable?: false): DateTime;
+/**
+ * Consumes a datetime value from database results with nullable support and enhanced string parsing
+ * @param key - The field name for error reporting
+ * @param value - The value to consume
+ * @param nullable - Whether the field can be null
+ * @returns The consumed DateTime value or null if nullable and value is null
+ * @throws E_INVALID_CONSUMED_VALUE when the value cannot be consumed
+ * @remarks For string values, attempts SQL format parsing first, then falls back to ISO format parsing
+ */
+export declare function consumeDateTime(key: string, value: unknown, nullable: true): DateTime | null;
+export declare function consumeDateTime(key: string, value: unknown, nullable?: false): DateTime;
+/**
+ * Consumes a binary value from database results with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to consume
+ * @param nullable - Whether the field can be null
+ * @returns The consumed LucidBinaryValue or null if nullable and value is null
+ * @throws E_INVALID_CONSUMED_VALUE when the value cannot be consumed
+ */
+export declare function consumeBinary(key: string, value: unknown, nullable: true): LucidBinaryValue | null;
+export declare function consumeBinary(key: string, value: unknown, nullable?: false): LucidBinaryValue;
+/**
+ * Consumes a number value from database results with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to consume
+ * @param nullable - Whether the field can be null
+ * @returns The consumed number value or null if nullable and value is null
+ * @throws E_INVALID_CONSUMED_VALUE when the value cannot be consumed
+ */
+export declare function consumeNumber(key: string, value: unknown, nullable: true): number | null;
+export declare function consumeNumber(key: string, value: unknown, nullable?: false): number;
+/**
+ * Consumes an integer value from database results with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to consume
+ * @param nullable - Whether the field can be null
+ * @returns The consumed integer value or null if nullable and value is null
+ * @throws E_INVALID_CONSUMED_VALUE when the value cannot be consumed
+ */
+export declare function consumeInteger(key: string, value: unknown, nullable: true): number | null;
+export declare function consumeInteger(key: string, value: unknown, nullable?: false): number;
+/**
+ * Consumes a bigint value from database results with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to consume
+ * @param nullable - Whether the field can be null
+ * @returns The consumed bigint value or null if nullable and value is null
+ * @throws E_INVALID_CONSUMED_VALUE when the value cannot be consumed
+ */
+export declare function consumeBigint(key: string, value: unknown, nullable: true): bigint | null;
+export declare function consumeBigint(key: string, value: unknown, nullable?: false): bigint;
+/**
+ * Consumes an unsigned integer value from database results with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to consume
+ * @param nullable - Whether the field can be null
+ * @returns The consumed unsigned integer value or null if nullable and value is null
+ * @throws E_INVALID_CONSUMED_VALUE when the value cannot be consumed
+ */
+export declare function consumeUnsignedint(key: string, value: unknown, nullable: true): number | null;
+export declare function consumeUnsignedint(key: string, value: unknown, nullable?: false): number;
+/**
+ * Consumes a boolean value from database results with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to consume
+ * @param nullable - Whether the field can be null
+ * @returns The consumed boolean value or null if nullable and value is null
+ * @throws E_INVALID_CONSUMED_VALUE when the value cannot be consumed
+ */
+export declare function consumeBoolean(key: string, value: unknown, nullable: true): boolean | null;
+export declare function consumeBoolean(key: string, value: unknown, nullable?: false): boolean;
+/**
+ * Consumes an object value from database results with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to consume
+ * @param nullable - Whether the field can be null
+ * @returns The consumed LucidPlainObject or null if nullable and value is null
+ * @throws E_INVALID_CONSUMED_VALUE when the value cannot be consumed
+ */
+export declare function consumeObject(key: string, value: unknown, nullable: true): LucidPlainObject | null;
+export declare function consumeObject(key: string, value: unknown, nullable?: false): LucidPlainObject;
+/**
+ * Consumes an array value from database results with nullable support
+ * @param key - The field name for error reporting
+ * @param value - The value to consume
+ * @param nullable - Whether the field can be null
+ * @returns The consumed array value or null if nullable and value is null
+ * @throws E_INVALID_CONSUMED_VALUE when the value cannot be consumed
+ */
+export declare function consumeArray(key: string, value: unknown, nullable: true): Array<unknown> | null;
+export declare function consumeArray(key: string, value: unknown, nullable?: false): Array<unknown>;

package/private/decorators.d.ts

@@ -0,0 +1,209 @@
+import type { LucidModel, ColumnOptions, ComputedOptions } from '@adonisjs/lucid/types/model';
+import type { HasOne, ManyToMany, HasManyThrough, ManyToManyRelationOptions, RelationOptions, ThroughRelationOptions } from '@adonisjs/lucid/types/relations';
+import type { ResourcefulColumnDefinition, ResourcefulComputedAccessorDefinition, ResourcefulRelationshipDefinition, AnySchema, StringSchema, DateSchema, BinarySchema, NumberSchema, BooleanSchema, ObjectSchema, ArraySchema, ResourcefulPropertySchema } from '@nhtio/lucid-resourceful/types';
+/**
+ * Options for date columns including autoCreate and autoUpdate flags.
+ *
+ * @example
+ * ```ts
+ * {
+ *   autoCreate: true,
+ *   autoUpdate: false,
+ *   nullable: false,
+ * }
+ * ```
+ */
+export type DateColumnOptions = DataTypeColumnOptions & {
+    autoCreate: boolean;
+    autoUpdate: boolean;
+};
+/**
+ * Options for relation decorators on related models.
+ *
+ * @example
+ * ```ts
+ * import { resourcefulBelongsTo } from '@nhtio/lucid-resourceful'
+ *
+ * class Post {
+ *   @resourcefulBelongsTo(() => User, { foreignKey: 'user_id' })
+ *   public user: User
+ * }
+ * ```
+ */
+export type RelatedModelRelationOptions<RelatedModel extends LucidModel> = RelationOptions<RelatedModel, LucidModel, HasOne<RelatedModel, LucidModel>> | ManyToManyRelationOptions<ManyToMany<RelatedModel>> | Omit<ThroughRelationOptions<RelatedModel, LucidModel, HasManyThrough<RelatedModel>>, 'throughModel'>;
+/**
+ * Options for hasManyThrough relation decorators.
+ *
+ * @example
+ * ```ts
+ * import { resourcefulHasManyThrough } from '@nhtio/lucid-resourceful'
+ *
+ * class User {
+ *   @resourcefulHasManyThrough([
+ *     () => Role,
+ *     () => UserRolePivot
+ *   ], { foreignKey: 'user_id' })
+ *   public roles: HasManyThrough<typeof Role>
+ * }
+ * ```
+ */
+export type HasManyThroughRelationOptions<RelatedModel extends LucidModel> = Omit<ThroughRelationOptions<RelatedModel, LucidModel, HasManyThrough<RelatedModel>>, 'throughModel'>;
+export type DataTypeColumnOptions = Omit<ColumnOptions, 'prepare' | 'consume'>;
+export type DataTypeComputedOptions = Omit<ComputedOptions, 'prepare' | 'consume'>;
+/**
+ * Decorator to define a resourceful column on a Lucid model property.
+ * Applies validation, metadata, and Lucid column options.
+ *
+ * @example
+ * ```ts
+ * import { resourcefulColumn, ResourcefulStringType } from '@nhtio/lucid-resourceful'
+ *
+ * class User {
+ *   @resourcefulColumn({ type: ResourcefulStringType({ minLength: 1, maxLength: 100 }), nullable: false })
+ *   public name: string
+ * }
+ * ```
+ *
+ * @param options - Resourceful column options and Lucid column options.
+ * @returns Property decorator function.
+ */
+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 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 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;
+}
+/**
+ * Decorator to define a resourceful computed accessor on a Lucid model property.
+ * Applies validation, metadata, and Lucid computed options.
+ *
+ * @example
+ * ```ts
+ * import { resourcefulComputed, ResourcefulStringType } from '@nhtio/lucid-resourceful'
+ *
+ * class User {
+ *   @resourcefulComputed({ type: ResourcefulStringType({ minLength: 1, maxLength: 100 }) })
+ *   public get fullName() {
+ *     return `${this.firstName} ${this.lastName}`
+ *   }
+ * }
+ * ```
+ *
+ * @param options - Resourceful computed accessor options and Lucid computed options.
+ * @returns Property decorator function.
+ */
+export declare function resourcefulComputed<Schema extends AnySchema = ResourcefulPropertySchema>(options?: Partial<ComputedOptions> & Partial<ResourcefulComputedAccessorDefinition<Schema>>): (target: any, propertyKey: string) => void;
+export declare namespace resourcefulComputed {
+    var string: (options?: Partial<DataTypeComputedOptions> & Partial<ResourcefulComputedAccessorDefinition<StringSchema>>) => (target: any, propertyKey: string) => void;
+    var date: (options?: Partial<DataTypeComputedOptions> & Partial<ResourcefulComputedAccessorDefinition<DateSchema>>) => (target: any, propertyKey: string) => void;
+    var dateTime: (options?: Partial<DataTypeComputedOptions> & Partial<ResourcefulComputedAccessorDefinition<DateSchema>>) => (target: any, propertyKey: string) => void;
+    var binary: (options?: Partial<DataTypeComputedOptions> & Partial<ResourcefulComputedAccessorDefinition<DateSchema>>) => (target: any, propertyKey: string) => void;
+    var number: (options?: Partial<DataTypeComputedOptions> & Partial<ResourcefulComputedAccessorDefinition<NumberSchema>>) => (target: any, propertyKey: string) => void;
+    var integer: (options?: Partial<DataTypeComputedOptions> & Partial<ResourcefulComputedAccessorDefinition<NumberSchema>>) => (target: any, propertyKey: string) => void;
+    var bigint: (options?: Partial<DataTypeComputedOptions> & Partial<ResourcefulComputedAccessorDefinition<NumberSchema>>) => (target: any, propertyKey: string) => void;
+    var unsignedint: (options?: Partial<DataTypeComputedOptions> & Partial<ResourcefulComputedAccessorDefinition<NumberSchema>>) => (target: any, propertyKey: string) => void;
+    var boolean: (options?: Partial<DataTypeComputedOptions> & Partial<ResourcefulComputedAccessorDefinition<BooleanSchema>>) => (target: any, propertyKey: string) => void;
+    var object: (options?: Partial<ComputedOptions> & Partial<ResourcefulComputedAccessorDefinition<ObjectSchema>>) => (target: any, propertyKey: string) => void;
+    var array: (options?: Partial<ComputedOptions> & Partial<ResourcefulComputedAccessorDefinition<ArraySchema>>) => (target: any, propertyKey: string) => void;
+}
+/**
+ * Decorator to define a resourceful belongsTo relationship on a Lucid model property.
+ *
+ * @example
+ * ```ts
+ * import { resourcefulBelongsTo } from '@nhtio/lucid-resourceful'
+ *
+ * class Post {
+ *   @resourcefulBelongsTo(() => User, { foreignKey: 'user_id' })
+ *   public user: User
+ * }
+ * ```
+ *
+ * @param model - Function returning the related model class.
+ * @param options - Relationship options and resourceful relationship definition.
+ * @returns Property decorator function.
+ */
+export declare function resourcefulBelongsTo<RelatedModel extends LucidModel>(model: () => RelatedModel, options?: Partial<RelationOptions<RelatedModel, LucidModel, HasOne<RelatedModel, LucidModel>>> & Partial<ResourcefulRelationshipDefinition>): (target: any, propertyKey: string) => void;
+/**
+ * Decorator to define a resourceful hasOne relationship on a Lucid model property.
+ *
+ * @example
+ * ```ts
+ * import { resourcefulHasOne } from '@nhtio/lucid-resourceful'
+ *
+ * class UserProfile {
+ *   @resourcefulHasOne(() => User, { foreignKey: 'user_id' })
+ *   public user: UserProfile
+ * }
+ * ```
+ *
+ * @param model - Function returning the related model class.
+ * @param options - Relationship options and resourceful relationship definition.
+ * @returns Property decorator function.
+ */
+export declare function resourcefulHasOne<RelatedModel extends LucidModel>(model: () => RelatedModel, options?: Partial<RelationOptions<RelatedModel, LucidModel, HasOne<RelatedModel, LucidModel>>> & Partial<ResourcefulRelationshipDefinition>): (target: any, propertyKey: string) => void;
+/**
+ * Decorator to define a resourceful hasMany relationship on a Lucid model property.
+ *
+ * @example
+ * ```ts
+ * import { resourcefulHasMany } from '@nhtio/lucid-resourceful'
+ *
+ * class User {
+ *   @resourcefulHasMany(() => Post, { foreignKey: 'user_id' })
+ *   public posts: HasMany<typeof Post>
+ * }
+ * ```
+ *
+ * @param model - Function returning the related model class.
+ * @param options - Relationship options and resourceful relationship definition.
+ * @returns Property decorator function.
+ */
+export declare function resourcefulHasMany<RelatedModel extends LucidModel>(model: () => RelatedModel, options?: Partial<RelationOptions<RelatedModel, LucidModel, HasOne<RelatedModel, LucidModel>>> & Partial<ResourcefulRelationshipDefinition>): (target: any, propertyKey: string) => void;
+/**
+ * Decorator to define a resourceful manyToMany relationship on a Lucid model property.
+ *
+ * @example
+ * ```ts
+ * import { resourcefulManyToMany } from '@nhtio/lucid-resourceful'
+ *
+ * class User {
+ *   @resourcefulManyToMany(() => Role, { pivotTable: 'role_user' })
+ *   public roles: ManyToMany<typeof Role>
+ * }
+ * ```
+ *
+ * @param model - Function returning the related model class.
+ * @param options - ManyToMany relationship options and resourceful relationship definition.
+ * @returns Property decorator function.
+ */
+export declare function resourcefulManyToMany<RelatedModel extends LucidModel>(model: () => RelatedModel, options?: Partial<ManyToManyRelationOptions<ManyToMany<RelatedModel>>> & Partial<ResourcefulRelationshipDefinition>): (target: any, propertyKey: string) => void;
+/**
+ * Decorator to define a resourceful hasManyThrough relationship on a Lucid model property.
+ *
+ * @example
+ * ```ts
+ * import { resourcefulHasManyThrough } from '@nhtio/lucid-resourceful'
+ *
+ * class User {
+ *   @resourcefulHasManyThrough([
+ *     () => Role,
+ *     () => UserRolePivot
+ *   ], { foreignKey: 'user_id' })
+ *   public roles: HasManyThrough<typeof Role>
+ * }
+ * ```
+ *
+ * @param model - Tuple of functions returning the related model and through model classes.
+ * @param options - HasManyThrough relationship options and resourceful relationship definition.
+ * @returns Property decorator function.
+ */
+export declare function resourcefulHasManyThrough<RelatedModel extends LucidModel>(model: [() => RelatedModel, () => LucidModel], options?: Partial<HasManyThroughRelationOptions<RelatedModel>> & Partial<ResourcefulRelationshipDefinition>): (target: any, propertyKey: string) => void;

package/private/helpers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Removes all properties with undefined values from an object.
+ * This utility function creates a new object containing only the properties
+ * that have defined values, effectively filtering out any undefined properties.
+ *
+ * @example
+ * ```typescript
+ * const input = {
+ *   name: 'John',
+ *   age: undefined,
+ *   email: 'john@example.com',
+ *   phone: undefined
+ * }
+ *
+ * const result = stripUndefinedValuesFromObject(input)
+ * // Result: { name: 'John', email: 'john@example.com' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Useful for cleaning up optional parameters before API calls
+ * const apiParams = stripUndefinedValuesFromObject({
+ *   userId: user.id,
+ *   filter: searchFilter || undefined,
+ *   limit: pageSize || undefined,
+ *   offset: currentPage ? currentPage * pageSize : undefined
+ * })
+ * ```
+ *
+ * @template T - The type of the input object, must extend Record<string, any>
+ * @param {T} obj - The object to filter, removing properties with undefined values
+ * @returns {T} A new object of the same type with undefined properties removed
+ */
+export declare const stripUndefinedValuesFromObject: <T extends Record<string, any>>(obj: T) => T;

package/private/joi/bigint.d.ts

@@ -0,0 +1,85 @@
+import type { AnySchema } from '../schema_types';
+import type { ExtensionFactory, Reference } from 'joi';
+/**
+ * A Joi extension that adds support for BigInt validation with comprehensive
+ * comparison operations and type coercion.
+ *
+ * @example
+ * ```typescript
+ * import { joi } from '@nhtio/lucid-resourceful/joi'
+ *
+ * const schema = joi.bigint()
+ *   .min(0n)
+ *   .max(1000n)
+ *   .required()
+ *
+ * // Validates and converts to BigInt
+ * const result = schema.validate("123") // Returns { value: 123n }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Works with all standard Joi methods
+ * const optionalSchema = joi.bigint()
+ *   .positive()
+ *   .optional()
+ *   .allow(null)
+ *   .default(0n)
+ * ```
+ *
+ * @public
+ */
+export declare const bigint: ExtensionFactory;
+/**
+ * Joi schema type for BigInt validation with comprehensive comparison operations.
+ *
+ * This interface extends the base Joi AnySchema to provide BigInt-specific
+ * validation methods including range checks, sign validation, and multiple checks.
+ *
+ * @example
+ * ```typescript
+ * import { joi } from '@nhtio/lucid-resourceful/joi'
+ *
+ * const schema: BigIntSchema = joi.bigint()
+ *   .min(0n)
+ *   .max(1000n)
+ *   .positive()
+ * ```
+ *
+ * @public
+ */
+export interface BigIntSchema<TSchema = bigint> extends AnySchema<TSchema> {
+    /**
+     * Validates that the BigInt is greater than the specified threshold
+     * @param limit - The threshold value to compare against
+     */
+    greater(limit: bigint | Reference): this;
+    /**
+     * Validates that the BigInt is less than the specified threshold
+     * @param limit - The threshold value to compare against
+     */
+    less(limit: bigint | Reference): this;
+    /**
+     * Validates that the BigInt is less than or equal to the specified maximum
+     * @param limit - The maximum allowed value
+     */
+    max(limit: bigint | Reference): this;
+    /**
+     * Validates that the BigInt is greater than or equal to the specified minimum
+     * @param limit - The minimum allowed value
+     */
+    min(limit: bigint | Reference): this;
+    /**
+     * Validates that the BigInt is a multiple of the specified factor
+     * @param limit - The factor that the value must be a multiple of
+     */
+    multiple(limit: bigint | Reference): this;
+    /**
+     * Validates that the BigInt is negative (less than zero)
+     */
+    negative(): this;
+    /**
+     * Validates that the BigInt is positive (greater than zero)
+     */
+    positive(): this;
+}