@things-factory/shell 8.0.0-beta.9 → 8.0.0

package/server/utils/get-query-builder-from-list-params.ts

@@ -0,0 +1,469 @@
+import { Brackets, EntityMetadata, Repository, SelectQueryBuilder, WhereExpressionBuilder } from 'typeorm'
+import { RelationMetadata } from 'typeorm/metadata/RelationMetadata'
+import { Filter, Sorting, Pagination, ListParam, InheritedValueType } from '../service/common-types/list-param'
+import { Domain } from '../service/domain/domain'
+
+/**
+ * Creates a TypeORM SelectQueryBuilder based on the provided parameters.
+ *
+ * @param options - An object containing the query building options.
+ * @param options.repository - The TypeORM repository for database operations.
+ * @param options.params - The ListParam object containing filters, sortings, and pagination.
+ * @param [options.domain] - Optional domain object for applying domain-specific filters.
+ * @param [options.alias] - The alias to be used in the SQL queries.
+ * @param [options.searchables] - List of columns that are searchable.
+ * @param [options.filtersMap] - Mapping of filter names to their corresponding columns or relation columns.
+ * @returns {SelectQueryBuilder<Type>} - The constructed SelectQueryBuilder instance.
+ */
+export function getQueryBuilderFromListParams<Type>(options: {
+  repository: Repository<Type>
+  params: ListParam
+  domain?: Domain
+  alias?: string
+  searchables?: string[]
+  filtersMap?: { [name: string]: { columnName: string; relationColumn?: string } }
+}): SelectQueryBuilder<Type> {
+  const { repository, params, domain, alias, searchables, filtersMap = {} } = options
+  const { inherited = InheritedValueType.None } = params || {}
+
+  const selectQueryBuilder = repository.createQueryBuilder(alias)
+  const entityAlias = selectQueryBuilder.alias
+
+  // Apply filters to the query
+  const columnFilters =
+    params.filters?.filter(filter => {
+      if (filter.operator === 'search') {
+        return false
+      }
+      if (filter.operator.toLowerCase().includes('like') && (!searchables || !searchables.includes(filter.name))) {
+        console.warn('"searchables" setting is required for LIKE searches to avoid heavy database load', filter.name)
+        return false
+      }
+      return true
+    }) || []
+
+  const searchFilters =
+    searchables instanceof Array
+      ? params.filters?.filter(filter => {
+          if (filter.operator !== 'search') {
+            return false
+          }
+          if (!searchables.includes(filter.name)) {
+            console.warn(
+              '"searchables" setting is required for LIKE searches to avoid heavy database load',
+              filter.name
+            )
+            return false
+          }
+          return true
+        }) || []
+      : []
+
+  const pagination = params.pagination
+  const sortings = params.sortings
+  const metadata = repository.metadata
+
+  // Apply column filters
+  if (columnFilters.length > 0) {
+    columnFilters.forEach(filter => {
+      addCondition(metadata, selectQueryBuilder, selectQueryBuilder, filter, filtersMap, true)
+    })
+  }
+
+  // Apply search filters
+  if (searchFilters.length > 0) {
+    selectQueryBuilder.andWhere(
+      new Brackets(qb => {
+        searchFilters.forEach(filter => {
+          addCondition(metadata, selectQueryBuilder, qb, filter, filtersMap, false)
+        })
+      })
+    )
+  }
+
+  // Apply domain filters
+  if (domain) {
+    if (!inherited || inherited === InheritedValueType.None) {
+      selectQueryBuilder.andWhere(`${entityAlias}.domain = :domain`, { domain: domain.id })
+    } else if (inherited === InheritedValueType.Include) {
+      selectQueryBuilder.andWhere(`${entityAlias}.domain IN (:...domains)`, {
+        domains: [domain.id, domain.parentId].filter(Boolean)
+      })
+    } else if (inherited === InheritedValueType.Only) {
+      selectQueryBuilder.andWhere(`${entityAlias}.domain = :domain`, { domain: domain.parentId || 'Impossible' })
+    } else {
+      selectQueryBuilder.andWhere(`${entityAlias}.domain = :domain`, { domain: 'Impossible' })
+    }
+  }
+
+  // Apply pagination
+  addPagination(selectQueryBuilder, pagination)
+
+  // Apply sorting
+  if (sortings && sortings.length > 0) {
+    addSorting(selectQueryBuilder, sortings, entityAlias, filtersMap, metadata)
+  }
+
+  return selectQueryBuilder
+}
+
+/**
+ * Adds pagination to the SelectQueryBuilder based on the provided Pagination object.
+ *
+ * @param selectQueryBuilder - The SelectQueryBuilder to which pagination should be applied.
+ * @param pagination - The Pagination object containing page and limit information.
+ */
+function addPagination<T>(selectQueryBuilder: SelectQueryBuilder<T>, pagination?: Pagination) {
+  if (pagination) {
+    const { page, limit } = pagination
+    if (page && limit && page > 0 && limit > 0) {
+      selectQueryBuilder.skip(limit * (page - 1)).take(limit)
+    } else if (limit && limit > 0) {
+      selectQueryBuilder.take(limit)
+    }
+  }
+}
+
+/**
+ * Adds a filtering condition to the SelectQueryBuilder based on the provided filter and mapping options.
+ *
+ * @param metadata - The EntityMetadata of the TypeORM entity.
+ * @param selectQueryBuilder - The SelectQueryBuilder to which the condition will be added.
+ * @param whereExpressionBuilder - The WhereExpressionBuilder to construct the where clause.
+ * @param filter - The Filter object containing the filter criteria.
+ * @param filtersMap - A mapping of filter names to column names and relation column names.
+ * @param andCondition - A flag indicating whether to use "AND" or "OR" for combining conditions.
+ */
+function addCondition<T>(
+  metadata: EntityMetadata,
+  selectQueryBuilder: SelectQueryBuilder<T>,
+  whereExpressionBuilder: WhereExpressionBuilder,
+  filter: Filter,
+  filtersMap: { [name: string]: { columnName: string; relationColumn?: string } } = {},
+  andCondition: boolean
+): void {
+  const { name, operator, value } = filter
+  var entityAlias = selectQueryBuilder.alias
+
+  var { relationColumn, columnName } = filtersMap[name] || {}
+  /*
+    1. relationColumn과 columnName이 지정된 경우 
+    - relation inverse 테이블에서, columnName을 찾는다.
+    2. relationColumn만 지정된 경우는 없어야 한다.
+    - 이 경우 columnName 은 'name' 이라고 판단한다.
+    3. columnName이 지정된 경우.
+    - 이 경우는 columnName 만 적용한다.
+  */
+  if (relationColumn) {
+    const columns = relationColumn.split('.')
+    var entityMetadata: EntityMetadata
+    var relation: RelationMetadata
+
+    for (const rcolumn of columns) {
+      if (relation) {
+        const { propertyName } = relationColumnMeta
+        const property = `${entityAlias}.${propertyName}`
+
+        entityAlias = `${entityAlias}-${entityMetadata.tableName}-for-${columnName || 'name'}` as string
+
+        if (andCondition) {
+          selectQueryBuilder.innerJoin(property, entityAlias)
+        } else {
+          selectQueryBuilder.leftJoin(property, entityAlias)
+        }
+      } else {
+        entityMetadata = metadata
+      }
+
+      var relationColumnMeta = entityMetadata.columns.find(column => column.propertyName === rcolumn)
+      if (!relationColumnMeta) {
+        console.warn(`relationColumn "${relationColumn}" in filtersMap for "${name}" is not a relation column`)
+        return
+      }
+
+      relation = relationColumnMeta.relationMetadata
+      entityMetadata = relation.inverseEntityMetadata
+    }
+
+    var columnMeta = entityMetadata.columns.find(column => column.propertyName === (columnName || 'name'))
+    if (!columnMeta) {
+      console.warn(`columnName "${columnName}" in filtersMap for "${name}" is not a column`)
+      return
+    }
+  } else {
+    var columnMeta = metadata.columns.find(column => column.propertyName === (columnName || name))
+    if (!columnMeta) {
+      /* relationId 에 대한 필터링은 해당 컬럼값 자체의 비교로 한다. */
+      var relationIdMeta = metadata.relationIds.find(relationId => relationId.propertyName === (columnName || name))
+      if (relationIdMeta) {
+        columnMeta = relationIdMeta.relation.joinColumns[0]
+      } else {
+        columnName
+          ? console.warn(`columnName "${columnName}" in filtersMap for "${name}" is not a column`)
+          : console.warn(`name "${name}" is not a column`)
+      }
+    } else {
+      var relation = columnMeta.relationMetadata
+    }
+
+    if (relation) {
+      /* filterMap에 의해서 relationColumn 이 지정되지 않았더라도, name 또는 columnName의 column이 relation인 경우에는
+        - 조건절 구성을 위한 타겟필드명은 'name' 으로만 한정된다.
+      */
+      var relationColumnMeta = columnMeta
+      var entityMetadata = relation.inverseEntityMetadata
+      columnMeta = entityMetadata.columns.find(column => column.propertyName === 'name')
+      if (!columnMeta) {
+        console.warn(`relation column "${columnName || name}" does not have "name" column`)
+        return
+      }
+    }
+  }
+
+  const dbNameForColumn = columnMeta.databaseName
+  const alias = relationColumnMeta ? `${name}-filter` : entityAlias
+
+  /* relation columne인 경우 name을 alias로 사용한다. */
+  const field = `${alias}.${dbNameForColumn}`
+
+  var { clause, parameters } = getClauseAndParameters(field, name, operator, value)
+
+  if (relationColumnMeta) {
+    const { propertyName } = relationColumnMeta
+    const property = `${entityAlias}.${propertyName}`
+    if (andCondition) {
+      selectQueryBuilder.innerJoin(property, alias, clause, parameters)
+    } else {
+      selectQueryBuilder.leftJoin(property, alias)
+      whereExpressionBuilder.orWhere(clause, parameters)
+    }
+  } else {
+    andCondition
+      ? whereExpressionBuilder.andWhere(clause, parameters)
+      : whereExpressionBuilder.orWhere(clause, parameters)
+  }
+}
+
+/**
+ * Adds sorting to the SelectQueryBuilder based on the provided Sorting objects.
+ *
+ * @param selectQueryBuilder - The SelectQueryBuilder to which sorting should be applied.
+ * @param sortings - An array of Sorting objects defining the sort order.
+ * @param entityAlias - The alias of the entity in the query.
+ * @param filtersMap - A mapping of filter names to column names and relation column names.
+ * @param metadata - The EntityMetadata of the TypeORM entity.
+ */
+function addSorting<T>(
+  selectQueryBuilder: SelectQueryBuilder<T>,
+  sortings: Sorting[],
+  entityAlias: string,
+  filtersMap: { [name: string]: { columnName: string; relationColumn?: string } },
+  metadata: EntityMetadata
+) {
+  sortings.forEach((sorting, index) => {
+    const sortField = determineSortField(sorting.name, entityAlias, filtersMap, selectQueryBuilder, metadata)
+    if (index === 0) {
+      selectQueryBuilder.orderBy(sortField, sorting.desc ? 'DESC' : 'ASC')
+    } else {
+      selectQueryBuilder.addOrderBy(sortField, sorting.desc ? 'DESC' : 'ASC')
+    }
+  })
+}
+
+/**
+ * Determines the sorting field for a given sorting name, considering possible relation columns.
+ *
+ * @param sortingName - The name of the field to sort by.
+ * @param entityAlias - The alias of the entity in the query.
+ * @param filtersMap - A mapping of filter names to column names and relation column names.
+ * @param selectQueryBuilder - The SelectQueryBuilder instance to apply sorting to.
+ * @param metadata - The EntityMetadata of the TypeORM entity.
+ * @returns {string} - The fully qualified sorting field.
+ */
+function determineSortField<T>(
+  sortingName: string,
+  entityAlias: string,
+  filtersMap: { [name: string]: { columnName: string; relationColumn?: string } },
+  selectQueryBuilder: SelectQueryBuilder<T>,
+  metadata: EntityMetadata
+): string {
+  const filter = filtersMap[sortingName]
+
+  if (!filter) {
+    return sortingName.split('.').length > 1 ? sortingName : `${entityAlias}.${sortingName}`
+  }
+
+  const { columnName, relationColumn } = filter
+
+  if (relationColumn) {
+    const relationAlias = applyJoins(
+      selectQueryBuilder,
+      entityAlias,
+      relationColumn,
+      metadata,
+      'leftJoin',
+      columnName || sortingName,
+      true
+    )
+    return `${relationAlias}.${columnName}`
+  } else {
+    return `${entityAlias}.${columnName}`
+  }
+}
+
+/**
+ * Applies the necessary joins to the SelectQueryBuilder based on the relation column.
+ *
+ * @param selectQueryBuilder - The SelectQueryBuilder where the joins will be applied.
+ * @param entityAlias - The current alias of the entity in the query.
+ * @param relationColumn - The dot-notated string representing the relation chain (e.g., "user.profile.address").
+ * @param metadata - The EntityMetadata of the entity.
+ * @param joinType - The type of join to use ("innerJoin" or "leftJoin").
+ * @param columnName - The name of the column used for filtering or sorting, default to 'name'.
+ * @param selectField - Whether to include the field in the SELECT clause.
+ * @returns {string} - The alias to be used for the final field in the relation chain.
+ */
+function applyJoins<T>(
+  selectQueryBuilder: SelectQueryBuilder<T>,
+  entityAlias: string,
+  relationColumn: string,
+  metadata: EntityMetadata,
+  joinType: 'innerJoin' | 'leftJoin' = 'leftJoin',
+  columnName: string = 'name',
+  selectField: boolean = false
+): string {
+  const columns = relationColumn.split('.')
+  let currentAlias = entityAlias
+  let currentMetadata = metadata
+
+  for (const column of columns) {
+    const relation = currentMetadata.relations.find(rel => rel.propertyName === column)
+
+    if (!relation) {
+      throw new Error(`Relation not found for column: ${column}`)
+    }
+
+    const nextAlias = `${currentAlias}_${relation.inverseEntityMetadata.tableName}_for_${columnName}`
+
+    if (!selectQueryBuilder.expressionMap.aliases.some(alias => alias.name === nextAlias)) {
+      selectQueryBuilder[joinType](`${currentAlias}.${column}`, nextAlias)
+    }
+    if (selectField && columns.at(-1) == column /* 최종 alias만 추가 */) {
+      selectQueryBuilder.addSelect(`${nextAlias}.${columnName}`, `${nextAlias}_${columnName}`)
+    }
+
+    currentAlias = nextAlias
+    currentMetadata = relation.inverseEntityMetadata
+  }
+
+  return currentAlias
+}
+
+/**
+ * Generates the SQL clause and parameters based on the provided filter.
+ *
+ * @param field - The database field to filter on.
+ * @param name - The name of the filter.
+ * @param operator - The operator to use in the filter.
+ * @param value - The value to filter with.
+ * @returns An object containing the SQL clause and the parameters.
+ */
+function getClauseAndParameters(
+  field: string,
+  name: string,
+  operator: string,
+  value: any
+): { clause: string; parameters: { [key: string]: any } } {
+  const values = value instanceof Array ? value : [value]
+  let clause = ''
+  let parameters: { [key: string]: any } = {}
+
+  switch (operator) {
+    case 'eq':
+      clause = `${field} = :${name}`
+      parameters = { [name]: value }
+      break
+    case 'like':
+      clause = `${field} LIKE :${name}`
+      parameters = { [name]: `%${value}%` }
+      break
+    case 'search':
+    case 'i_like':
+      clause = `LOWER(${field}) LIKE :${name}`
+      parameters = { [name]: `%${String(value).toLowerCase()}%` }
+      break
+    case 'nlike':
+      clause = `${field} NOT LIKE :${name}`
+      parameters = { [name]: `%${value}%` }
+      break
+    case 'i_nlike':
+      clause = `LOWER(${field}) NOT LIKE :${name}`
+      parameters = { [name]: `%${String(value).toLowerCase()}%` }
+      break
+    case 'lt':
+      clause = `${field} < :${name}`
+      parameters = { [name]: value }
+      break
+    case 'gt':
+      clause = `${field} > :${name}`
+      parameters = { [name]: value }
+      break
+    case 'lte':
+      clause = `${field} <= :${name}`
+      parameters = { [name]: value }
+      break
+    case 'gte':
+      clause = `${field} >= :${name}`
+      parameters = { [name]: value }
+      break
+    case 'noteq':
+      clause = `${field} != :${name}`
+      parameters = { [name]: value }
+      break
+    case 'in':
+      clause = `${field} IN (:...${name})`
+      parameters = { [name]: values }
+      break
+    case 'notin':
+      clause = `${field} NOT IN (:...${name})`
+      parameters = { [name]: values }
+      break
+    case 'notin_with_null':
+      clause = `${field} IS NULL OR ${field} NOT IN (:...${name})`
+      parameters = { [name]: values }
+      break
+    case 'is_null':
+      clause = `${field} IS NULL`
+      break
+    case 'is_not_null':
+      clause = `${field} IS NOT NULL`
+      break
+    case 'is_false':
+      clause = `${field} IS FALSE`
+      break
+    case 'is_true':
+      clause = `${field} IS TRUE`
+      break
+    case 'is_not_false':
+      clause = `${field} IS NOT FALSE`
+      break
+    case 'is_not_true':
+      clause = `${field} IS NOT TRUE`
+      break
+    case 'is_present':
+      clause = `${field} IS PRESENT`
+      break
+    case 'is_blank':
+      clause = `${field} IS BLANK`
+      break
+    case 'is_empty_num_id':
+      clause = `${field} IS EMPTY NUMERIC ID`
+      break
+    case 'between':
+      clause = `${field} BETWEEN  :${name}_1 AND :${name}_2`
+      parameters = { [`${name}_1`]: values[0], [`${name}_2`]: values[1] }
+      break
+  }
+
+  return { clause, parameters }
+}

package/server/utils/get-times-for-period.ts

@@ -0,0 +1,60 @@
+import moment from 'moment-timezone'
+
+/**
+ * Get the time range for the specified period relative to the current moment in a specific domain's timezone.
+ *
+ * @param {string} period - The time period to calculate the range for. Valid options are 'today', 'this month', '30 days', 'this year', '12 months'.
+ * @param {Object} context - The context object containing domain information.
+ * @returns {Promise<{ from: string; to: string }>} - A Promise that resolves to an object containing 'from' and 'to' ISO date strings representing the time range.
+ */
+export async function getTimesForPeriod(period: 'today' | 'this month' | '30 days' | 'this year' | '12 months', context: any): Promise<{ from: string; to: string }> {
+  const { domain } = context.state
+  const theDate = moment.tz(new Date(), domain.timezone)
+
+  if (period == 'today') {
+    const from = theDate.clone().format('YYYY-MM-DD')
+    const to = theDate.clone().add(1, 'day').startOf('day').format('YYYY-MM-DD')
+
+    return { from, to }
+  } else if (period == 'this month') {
+    const from = theDate.clone().startOf('month').format('YYYY-MM-DD')
+    const to = theDate.clone().add(1, 'month').startOf('month').format('YYYY-MM-DD')
+
+    return { from, to }
+  } else if (period == '30 days') {
+    const from = theDate.clone().subtract(30, 'day').format('YYYY-MM-DD')
+    const to = theDate.clone().add(1, 'day').startOf('day').format('YYYY-MM-DD')
+
+    return { from, to }
+  } else if (period == 'this year') {
+    const from = theDate.clone().startOf('year').format('YYYY-MM-DD')
+    const to = theDate.clone().add(1, 'year').startOf('year').format('YYYY-MM-DD')
+
+    return { from, to }
+  } else if (period == '12 months') {
+    const from = theDate.clone().subtract(12, 'month').startOf('month').format('YYYY-MM-DD')
+    const to = theDate.clone().add(1, 'month').startOf('month').format('YYYY-MM-DD')
+
+    return { from, to }
+  }
+}
+
+/**
+ * Get the ISO date strings for the specified period relative to the current moment in a specific domain's timezone.
+ *
+ * @param {string} period - The time period to calculate the range for. Valid options are 'today', 'this month', '30 days', 'this year', '12 months'.
+ * @param {Object} context - The context object containing domain information.
+ * @returns {Promise<{ from: string; to: string }>} - A Promise that resolves to an object containing 'from' and 'to' ISO date strings representing the time range.
+ */
+export async function getISOStringsForPeriod(
+  period: 'today' | 'this month' | '30 days' | 'this year' | '12 months',
+  context: any
+): Promise<{ from: string; to: string }> {
+  const { domain } = context.state
+  const { from, to } = await getTimesForPeriod(period, context)
+
+  return {
+    from: moment.tz(from, domain.timezone).toISOString(),
+    to: moment.tz(to, domain.timezone).toISOString()
+  }
+}

package/server/utils/index.ts

@@ -0,0 +1,8 @@
+export * from './get-domain'
+export * from './condition-builder'
+export * from './list-query-builder'
+export * from './list-params-converter'
+export * from './publish-progress'
+export * from './get-query-builder-from-list-params'
+export * from './list-param-adjuster'
+export * from './get-times-for-period'

package/server/utils/list-param-adjuster.ts

@@ -0,0 +1,21 @@
+import { Filter } from '../service/common-types'
+
+/**
+ * Adjust the given array of filters based on the provided changes.
+ * If a filter with the same name exists in the original array, it will be replaced with the new filter;
+ * otherwise, the new filter will be added to the array.
+ *
+ * @param {Filter[]} filters - The original array of filters to be adjusted.
+ * @param {Filter[]} filtersChange - The array of filter changes to be applied.
+ * @returns {Filter[]} - The adjusted array of filters.
+ */
+export function adjustFilters(filters: Filter[], filtersChange: Filter[]): Filter[] {
+  var filtersNew = [...filters]
+
+  filtersChange.forEach(change => {
+    const idx = (filtersNew || []).findIndex(f => f.name === change.name)
+    idx !== -1 ? filtersNew.splice(idx, 1, change) : filtersNew.push(change)
+  })
+
+  return filtersNew
+}