@umituz/react-native-firebase 2.5.1 → 2.6.1

package/src/domains/firestore/domain/services/QueryService.ts

@@ -0,0 +1,182 @@
+/**
+ * Query Service (Main Builder)
+ * Single Responsibility: Build and validate Firestore queries
+ *
+ * Domain service that encapsulates query building logic.
+ * Moves business logic from infrastructure to domain layer.
+ *
+ * Max lines: 150 (enforced for maintainability)
+ */
+
+import type { Query, Firestore, WhereFilterOp } from 'firebase/firestore';
+import { collection, query, where, orderBy, limit, startAfter, startAt } from 'firebase/firestore';
+import { QueryOptions, createQueryOptions } from '../value-objects/QueryOptions';
+import { WhereClause } from '../value-objects/WhereClause';
+
+/**
+ * Query builder result
+ */
+export interface QueryBuilderResult {
+  readonly query: Query;
+  readonly options: QueryOptions;
+}
+
+/**
+ * Query service
+ * Provides query building and validation functionality
+ */
+export class QueryService {
+  private readonly db: Firestore;
+
+  constructor(db: Firestore) {
+    this.db = db;
+  }
+
+  /**
+   * Build a query from options
+   * Main method for query construction
+   */
+  buildQuery(collectionPath: string, options: QueryOptions): QueryBuilderResult {
+    const validation = options.validate();
+    if (!validation.valid) {
+      throw new Error(`Invalid query options: ${validation.errors.join(', ')}`);
+    }
+
+    const collectionRef = collection(this.db, collectionPath);
+    let q: Query = collectionRef;
+
+    // Apply where clauses
+    for (const clause of options.whereClauses) {
+      q = query(q, where(clause.field, clause.operator, clause.value));
+    }
+
+    // Apply sort options
+    for (const sort of options.sortOptions) {
+      q = query(q, orderBy(sort.field, sort.direction));
+    }
+
+    // Apply date range
+    if (options.dateRange) {
+      const { field, startDate, endDate } = options.dateRange;
+      if (startDate) {
+        q = query(q, where(field, '>=', startDate));
+      }
+      if (endDate) {
+        q = query(q, where(field, '<=', endDate));
+      }
+    }
+
+    // Apply pagination
+    if (options.pagination) {
+      const { cursor, limit: limitValue, startAfter: startAfterValue, startAt: startAtValue } = options.pagination;
+
+      if (startAfterValue !== undefined) {
+        q = query(q, startAfter(startAfterValue));
+      }
+
+      if (startAtValue !== undefined) {
+        q = query(q, startAt(startAtValue));
+      }
+
+      if (limitValue !== undefined) {
+        q = query(q, limit(limitValue));
+      }
+    }
+
+    return { query: q, options };
+  }
+
+  /**
+   * Build simple query with single where clause
+   */
+  buildSimpleQuery(
+    collectionPath: string,
+    field: string,
+    operator: WhereFilterOp,
+    value: unknown
+  ): Query {
+    const options = createQueryOptions({
+      where: [WhereClause.create(field, operator, value)],
+    });
+
+    return this.buildQuery(collectionPath, options).query;
+  }
+
+  /**
+   * Build query with equality filter
+   */
+  buildEqualsQuery(collectionPath: string, field: string, value: unknown): Query {
+    return this.buildSimpleQuery(collectionPath, field, '==', value);
+  }
+
+  /**
+   * Build query with multiple equality filters
+   */
+  buildMultiEqualsQuery(
+    collectionPath: string,
+    filters: Record<string, unknown>
+  ): Query {
+    const whereClauses = Object.entries(filters).map(([field, value]) =>
+      WhereClause.equals(field, value)
+    );
+
+    const options = createQueryOptions({ where: whereClauses });
+    return this.buildQuery(collectionPath, options).query;
+  }
+
+  /**
+   * Build query with sorting
+   */
+  buildSortedQuery(
+    collectionPath: string,
+    sortField: string,
+    direction: 'asc' | 'desc' = 'asc'
+  ): Query {
+    const options = createQueryOptions({
+      sort: [{ field: sortField, direction }],
+    });
+
+    return this.buildQuery(collectionPath, options).query;
+  }
+
+  /**
+   * Build query with limit
+   */
+  buildLimitedQuery(collectionPath: string, limitValue: number): Query {
+    const options = createQueryOptions({
+      pagination: { limit: limitValue },
+    });
+
+    return this.buildQuery(collectionPath, options).query;
+  }
+
+  /**
+   * Build query with date range
+   */
+  buildDateRangeQuery(
+    collectionPath: string,
+    field: string,
+    startDate?: Date,
+    endDate?: Date
+  ): Query {
+    const options = createQueryOptions({
+      dateRange: { field, startDate, endDate },
+    });
+
+    return this.buildQuery(collectionPath, options).query;
+  }
+
+  /**
+   * Validate query options
+   */
+  validateOptions(options: QueryOptions): { valid: boolean; errors: string[] } {
+    return options.validate();
+  }
+
+  /**
+   * Check if query is empty (no filters)
+   */
+  isEmptyQuery(options: QueryOptions): boolean {
+    return options.isEmpty();
+  }
+}

package/src/domains/firestore/domain/services/QueryServiceAnalysis.ts

@@ -0,0 +1,169 @@
+/**
+ * Query Service Analysis
+ * Single Responsibility: Analyze query complexity and metadata
+ *
+ * Provides analysis functionality for query options.
+ * Extracts field information and calculates complexity scores.
+ *
+ * Max lines: 150 (enforced for maintainability)
+ */
+
+import { QueryOptions } from '../value-objects/QueryOptions';
+
+/**
+ * Extract field names from query options
+ */
+export function extractFields(options: QueryOptions): string[] {
+  const fields = new Set<string>();
+
+  for (const clause of options.whereClauses) {
+    fields.add(clause.field);
+  }
+
+  for (const sort of options.sortOptions) {
+    fields.add(sort.field);
+  }
+
+  if (options.dateRange) {
+    fields.add(options.dateRange.field);
+  }
+
+  return Array.from(fields);
+}
+
+/**
+ * Check if query uses array operators
+ */
+export function hasArrayOperators(options: QueryOptions): boolean {
+  return options.whereClauses.some(clause => clause.isArrayOperator());
+}
+
+/**
+ * Check if query uses membership operators
+ */
+export function hasMembershipOperators(options: QueryOptions): boolean {
+  return options.whereClauses.some(clause => clause.isMembership());
+}
+
+/**
+ * Get query complexity score
+ * Higher score = more complex query
+ */
+export function getComplexityScore(options: QueryOptions): number {
+  let score = 0;
+
+  score += options.whereClauses.length * 1;
+  score += options.sortOptions.length * 2;
+  score += options.dateRange ? 3 : 0;
+  score += options.pagination?.limit ? 1 : 0;
+
+  // Array and membership operators add complexity
+  if (hasArrayOperators(options)) score += 5;
+  if (hasMembershipOperators(options)) score += 5;
+
+  return score;
+}
+
+/**
+ * Check if query is too complex
+ */
+export function isTooComplex(options: QueryOptions, maxScore: number = 20): boolean {
+  return getComplexityScore(options) > maxScore;
+}
+
+/**
+ * Get query statistics
+ */
+export function getQueryStats(options: QueryOptions): {
+  readonly whereClauseCount: number;
+  readonly sortOptionCount: number;
+  readonly hasDateRange: boolean;
+  readonly hasPagination: boolean;
+  readonly complexityScore: number;
+  readonly fieldCount: number;
+} {
+  return {
+    whereClauseCount: options.whereClauses.length,
+    sortOptionCount: options.sortOptions.length,
+    hasDateRange: options.hasDateRange(),
+    hasPagination: options.hasPagination(),
+    complexityScore: getComplexityScore(options),
+    fieldCount: extractFields(options).length,
+  };
+}
+
+/**
+ * Check if query is simple (low complexity)
+ */
+export function isSimpleQuery(options: QueryOptions, maxScore: number = 5): boolean {
+  return getComplexityScore(options) <= maxScore;
+}
+
+/**
+ * Check if query is moderate complexity
+ */
+export function isModerateQuery(options: QueryOptions): boolean {
+  const score = getComplexityScore(options);
+  return score > 5 && score <= 15;
+}
+
+/**
+ * Check if query is high complexity
+ */
+export function isComplexQuery(options: QueryOptions): boolean {
+  return getComplexityScore(options) > 15;
+}
+
+/**
+ * Get query complexity level
+ */
+export function getComplexityLevel(options: QueryOptions): 'simple' | 'moderate' | 'complex' {
+  if (isSimpleQuery(options)) {
+    return 'simple';
+  }
+
+  if (isModerateQuery(options)) {
+    return 'moderate';
+  }
+
+  return 'complex';
+}
+
+/**
+ * Compare two queries by complexity
+ */
+export function compareComplexity(options1: QueryOptions, options2: QueryOptions): number {
+  const score1 = getComplexityScore(options1);
+  const score2 = getComplexityScore(options2);
+
+  return score1 - score2;
+}
+
+/**
+ * Get query performance hints
+ */
+export function getPerformanceHints(options: QueryOptions): string[] {
+  const hints: string[] = [];
+
+  if (hasArrayOperators(options)) {
+    hints.push('Array operators can impact performance');
+  }
+
+  if (hasMembershipOperators(options)) {
+    hints.push('Membership operators (in, not-in) are limited to 10 values');
+  }
+
+  if (options.whereClauses.length > 5) {
+    hints.push('Consider reducing number of where clauses');
+  }
+
+  if (!options.pagination?.limit && options.sortOptions.length > 0) {
+    hints.push('Add limit to prevent full collection scans');
+  }
+
+  if (options.dateRange && !options.sortOptions.some(s => s.field === options.dateRange?.field)) {
+    hints.push('Add sort on date range field for better performance');
+  }
+
+  return hints;
+}

package/src/domains/firestore/domain/services/QueryServiceHelpers.ts

@@ -0,0 +1,151 @@
+/**
+ * Query Service Helpers
+ * Single Responsibility: Provide helper methods for query operations
+ *
+ * Helper methods for query options manipulation and creation.
+ * Separated from main QueryService for better maintainability.
+ *
+ * Max lines: 150 (enforced for maintainability)
+ */
+
+import type { Query } from 'firebase/firestore';
+import { QueryOptions, createQueryOptions } from '../value-objects/QueryOptions';
+import { WhereClause } from '../value-objects/WhereClause';
+import type { Collection } from '../entities/Collection';
+import type { QueryBuilderResult } from './QueryService';
+
+/**
+ * Create query options from filters object
+ */
+export function createOptionsFromFilters(filters: Record<string, unknown>): QueryOptions {
+  const whereClauses = Object.entries(filters).map(([field, value]) =>
+    WhereClause.equals(field, value)
+  );
+
+  return createQueryOptions({ where: whereClauses });
+}
+
+/**
+ * Merge multiple query options
+ * Later options override earlier ones for conflicting settings
+ */
+export function mergeOptions(...options: QueryOptions[]): QueryOptions {
+  if (options.length === 0) {
+    return createQueryOptions();
+  }
+
+  if (options.length === 1) {
+    return options[0];
+  }
+
+  const merged = options.reduce((acc, opt) => {
+    return QueryOptions.create({
+      where: [...acc.whereClauses, ...opt.whereClauses] as WhereClause[],
+      sort: opt.sortOptions.length > 0 ? [...opt.sortOptions] as any[] : [...acc.sortOptions] as any[],
+      dateRange: opt.dateRange ?? acc.dateRange,
+      pagination: opt.pagination ?? acc.pagination,
+    });
+  });
+
+  return merged ?? createQueryOptions();
+}
+
+/**
+ * Create paginated query options
+ */
+export function createPaginatedOptions(limit: number, cursor?: number): QueryOptions {
+  return createQueryOptions({
+    pagination: { limit, cursor },
+  });
+}
+
+/**
+ * Create sorted query options
+ */
+export function createSortedOptions(
+  field: string,
+  direction: 'asc' | 'desc' = 'asc'
+): QueryOptions {
+  return createQueryOptions({
+    sort: [{ field, direction }],
+  });
+}
+
+/**
+ * Optimize query options
+ * Removes redundant clauses and sorts
+ */
+export function optimizeOptions(options: QueryOptions): QueryOptions {
+  // Remove duplicate where clauses
+  const uniqueWheres = options.whereClauses.filter((clause, index, self) =>
+    index === self.findIndex(c => c.equals(clause))
+  );
+
+  // Remove duplicate sorts
+  const uniqueSorts = options.sortOptions.filter((sort, index, self) =>
+    index === self.findIndex(s => s.field === sort.field && s.direction === sort.direction)
+  );
+
+  return QueryOptions.create({
+    where: uniqueWheres,
+    sort: uniqueSorts,
+    dateRange: options.dateRange,
+    pagination: options.pagination,
+  });
+}
+
+/**
+ * Build query from collection entity
+ */
+export function buildQueryFromCollection(
+  collection: Collection,
+  options: QueryOptions,
+  queryService: any
+): QueryBuilderResult {
+  return queryService.buildQuery(collection.getPath(), options);
+}
+
+/**
+ * Get query description for logging
+ */
+export function describeQuery(options: QueryOptions): string {
+  const parts: string[] = [];
+
+  if (options.hasWhereClauses()) {
+    parts.push(`where: ${options.whereClauses.length} clause(s)`);
+  }
+
+  if (options.hasSort()) {
+    parts.push(`sort: ${options.sortOptions.length} field(s)`);
+  }
+
+  if (options.hasDateRange()) {
+    parts.push('date range: yes');
+  }
+
+  if (options.hasPagination()) {
+    parts.push(`limit: ${options.pagination?.limit || 'none'}`);
+  }
+
+  return parts.length > 0 ? parts.join(', ') : 'no filters';
+}
+
+/**
+ * Clone query options with modifications
+ */
+export function cloneOptions(
+  base: QueryOptions,
+  modifications: {
+    where?: WhereClause[];
+    sort?: Array<{ field: string; direction: 'asc' | 'desc' }>;
+    dateRange?: { field: string; startDate?: Date; endDate?: Date };
+    pagination?: { limit?: number; cursor?: number };
+  }
+): QueryOptions {
+  return QueryOptions.create({
+    where: modifications.where ?? [...base.whereClauses] as WhereClause[],
+    sort: modifications.sort ?? [...base.sortOptions] as any[],
+    dateRange: modifications.dateRange ?? base.dateRange ?? undefined,
+    pagination: modifications.pagination ?? base.pagination ?? undefined,
+  });
+}

package/src/domains/firestore/domain/value-objects/QueryOptions.ts

@@ -0,0 +1,191 @@
+/**
+ * Query Options Value Object (Main)
+ * Single Responsibility: Encapsulate query configuration options
+ *
+ * Value object that represents query options in a type-safe way.
+ * Provides validation and business logic for query configuration.
+ *
+ * Max lines: 150 (enforced for maintainability)
+ */
+
+import type { WhereFilterOp, OrderByDirection } from 'firebase/firestore';
+import { WhereClause } from './WhereClause';
+
+/**
+ * Sort options
+ */
+export interface SortOptions {
+  readonly field: string;
+  readonly direction: OrderByDirection;
+}
+
+/**
+ * Date range options
+ */
+export interface DateRangeOptions {
+  readonly field: string;
+  readonly startDate?: Date;
+  readonly endDate?: Date;
+}
+
+/**
+ * Pagination options
+ */
+export interface PaginationOptions {
+  readonly cursor?: number;
+  readonly limit?: number;
+  readonly startAfter?: number;
+  readonly startAt?: number;
+}
+
+/**
+ * Query options value object
+ * Immutable configuration for Firestore queries
+ */
+export class QueryOptions {
+  readonly whereClauses: readonly WhereClause[];
+  readonly sortOptions: readonly SortOptions[];
+  readonly dateRange: DateRangeOptions | null;
+  readonly pagination: PaginationOptions | null;
+
+  private constructor(
+    whereClauses: WhereClause[],
+    sortOptions: SortOptions[],
+    dateRange: DateRangeOptions | null,
+    pagination: PaginationOptions | null
+  ) {
+    this.whereClauses = Object.freeze(whereClauses);
+    this.sortOptions = Object.freeze(sortOptions);
+    this.dateRange = dateRange ? Object.freeze(dateRange) : null;
+    this.pagination = pagination ? Object.freeze(pagination) : null;
+  }
+
+  /**
+   * Create empty query options
+   */
+  static empty(): QueryOptions {
+    return new QueryOptions([], [], null, null);
+  }
+
+  /**
+   * Create query options from partial configuration
+   */
+  static create(options: {
+    where?: WhereClause[];
+    sort?: SortOptions[];
+    dateRange?: DateRangeOptions;
+    pagination?: PaginationOptions;
+  }): QueryOptions {
+    return new QueryOptions(
+      options.where || [],
+      options.sort || [],
+      options.dateRange || null,
+      options.pagination || null
+    );
+  }
+
+  /**
+   * Add where clause
+   */
+  withWhere(clause: WhereClause): QueryOptions {
+    return new QueryOptions(
+      [...this.whereClauses, clause] as WhereClause[],
+      this.sortOptions,
+      this.dateRange,
+      this.pagination
+    );
+  }
+
+  /**
+   * Add sort option
+   */
+  withSort(sort: SortOptions): QueryOptions {
+    return new QueryOptions(
+      this.whereClauses,
+      [...this.sortOptions, sort] as SortOptions[],
+      this.dateRange,
+      this.pagination
+    );
+  }
+
+  /**
+   * Set date range
+   */
+  withDateRange(dateRange: DateRangeOptions): QueryOptions {
+    return new QueryOptions(
+      this.whereClauses,
+      this.sortOptions,
+      dateRange,
+      this.pagination
+    );
+  }
+
+  /**
+   * Set pagination
+   */
+  withPagination(pagination: PaginationOptions): QueryOptions {
+    return new QueryOptions(
+      this.whereClauses,
+      this.sortOptions,
+      this.dateRange,
+      pagination
+    );
+  }
+
+  /**
+   * Remove all where clauses
+   */
+  clearWhere(): QueryOptions {
+    return new QueryOptions([], this.sortOptions, this.dateRange, this.pagination);
+  }
+
+  /**
+   * Remove all sort options
+   */
+  clearSort(): QueryOptions {
+    return new QueryOptions(this.whereClauses, [], this.dateRange, this.pagination);
+  }
+
+  /**
+   * Remove date range
+   */
+  clearDateRange(): QueryOptions {
+    return new QueryOptions(this.whereClauses, this.sortOptions, null, this.pagination);
+  }
+
+  /**
+   * Remove pagination
+   */
+  clearPagination(): QueryOptions {
+    return new QueryOptions(this.whereClauses, this.sortOptions, this.dateRange, null);
+  }
+
+  /**
+   * Clone with modifications
+   */
+  clone(modifications: {
+    where?: WhereClause[];
+    sort?: SortOptions[];
+    dateRange?: DateRangeOptions | null;
+    pagination?: PaginationOptions | null;
+  }): QueryOptions {
+    return QueryOptions.create({
+      where: modifications.where ?? [...this.whereClauses] as WhereClause[],
+      sort: modifications.sort ?? [...this.sortOptions] as SortOptions[],
+      dateRange: modifications.dateRange ?? this.dateRange ?? null,
+      pagination: modifications.pagination ?? this.pagination ?? null,
+    });
+  }
+}
+
+/**
+ * Factory function to create query options
+ */
+export function createQueryOptions(options?: {
+  where?: WhereClause[];
+  sort?: SortOptions[];
+  dateRange?: DateRangeOptions;
+  pagination?: PaginationOptions;
+}): QueryOptions {
+  return options ? QueryOptions.create(options) : QueryOptions.empty();
+}