@nhtio/lucid-resourceful 1.20250718.0

package/private/joi/index.d.ts

@@ -0,0 +1,65 @@
+import type { Root } from 'joi';
+import type { BigIntSchema } from './bigint';
+/**
+ * Extended Joi root interface that includes custom schema types for
+ * lucid-resourceful validation scenarios.
+ *
+ * This interface extends the standard Joi Root interface to include
+ * additional schema types specifically designed for AdonisJS Lucid
+ * model validation requirements.
+ *
+ * @example
+ * ```typescript
+ * import { joi } from '@nhtio/lucid-resourceful/joi'
+ *
+ * const schema = joi.object({
+ *   id: joi.bigint().positive().required(),
+ *   balance: joi.bigint().min(0n).optional()
+ * })
+ * ```
+ *
+ * @public
+ */
+export interface ExtendedJoiRoot extends Root {
+    /**
+     * Creates a BigInt schema type for validation
+     * @returns A new BigInt schema instance
+     */
+    bigint(): BigIntSchema;
+}
+/**
+ * Extended Joi instance with custom schema types for lucid-resourceful.
+ *
+ * This instance includes all standard Joi functionality plus additional
+ * schema types optimized for AdonisJS Lucid model validation scenarios.
+ *
+ * @example
+ * ```typescript
+ * import { joi } from '@nhtio/lucid-resourceful/joi'
+ *
+ * // Standard Joi usage
+ * const userSchema = joi.object({
+ *   name: joi.string().required(),
+ *   age: joi.number().min(0),
+ *   balance: joi.bigint().positive() // Custom BigInt type
+ * })
+ *
+ * // Use in resourceful decorators
+ * @resourceful({
+ *   type: 'bigint',
+ *   validate: {
+ *     create: joi.bigint().positive(),
+ *     update: joi.bigint().min(0n)
+ *   }
+ * })
+ * public balance: bigint
+ * ```
+ *
+ * @public
+ */
+export declare const joi: ExtendedJoiRoot;
+/**
+ * Re-export of the BigIntSchema interface for external use
+ * @public
+ */
+export type { BigIntSchema };

package/private/lucene_to_lucid_translator.d.ts

@@ -0,0 +1,201 @@
+import type { ModelKeysContract } from '@adonisjs/lucid/types/model';
+import type { QueryClientContract } from '@adonisjs/lucid/types/database';
+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';
+/**
+ * Database query builder contract extended for Lucene filtering capabilities.
+ *
+ * @template Result - The result type for the query builder
+ */
+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;
+/**
+ * Converts a Lucene query string to a Lucid database query builder.
+ * Parses the Lucene syntax and applies the resulting AST to generate SQL conditions.
+ *
+ * @template T - The result type for the query builder
+ * @param luceneQuery - The Lucene query string to parse and convert
+ * @param connection - The database connection client for creating queries
+ * @param attributesToColumns - Mapping of model attributes to database columns
+ * @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
+ * @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;