API Reference

Complete API reference for query operations including findAll, findById, findBy, and advanced filtering methods

findAll()

Retrieves all entities from the data source with optional filtering and relations.

Parameters

Prop	Type	Default
`opts?`	`QueryOpts<T, TResult, TRels>`	-

Returns

Returns Promise<TResult> where TResult is based on whether relations are included:

Without relations: T['$inferSelect'][]
With relations: RelationType<T, TRels>[]

Example

// Basic usage
const todos = await todosService.findAll()
console.log(`Found ${todos.length} todos`)

// With pagination and ordering
const paginatedTodos = await todosService.findAll({
  page: 1,
  limit: 10,
  orderBy: { createdAt: 'desc' }
})

// With workspace filtering
const workspaceTodos = await todosService.findAll({
  workspace: {
    field: 'tenant',
    value: 'company-abc'
  }
})

findById()

Finds a single entity by its unique identifier.

Parameters

Prop	Type	Default
`id`	`IdType<T, TOpts>`	-

Returns

Returns Promise<TResult | null> where TResult defaults to T['$inferSelect'].

Example

const todo = await todosService.findById('todo-123')

if (todo) {
  console.log('Found todo:', todo.title)
  console.log('Status:', todo.status)
} else {
  console.log('Todo not found')
}

// Non-existent ID returns null
const nonExistent = await todosService.findById('non-existent-id')
console.log(nonExistent) // null

findBy()

Finds entities that match the specified criteria using exact matching (AND condition).

Parameters

Prop	Type	Default
`opts?`	`QueryOpts<T, TResult, TRels>`	-
`criteria`	`Partial<T['$inferSelect']>`	-

Returns

Returns Promise<TResult> where TResult is based on whether relations are included.

Example

// Find todos by multiple criteria (AND condition)
const todos = await todosService.findBy({
  userId: 'user-123',
  priority: 'high'
})

// All returned todos match ALL criteria
todos.forEach(todo => {
  console.log(`${todo.title} - User: ${todo.userId}, Priority: ${todo.priority}`)
})

// Find completed todos
const completedTodos = await todosService.findBy({ status: 'done' })
console.log(`Found ${completedTodos.length} completed todos`)

findByMatching()

Finds entities that match any of the specified criteria using OR condition logic.

Parameters

Prop	Type	Default
`opts?`	`QueryOpts<T, TResult, TRels>`	-
`criteria`	`Partial<T['$inferSelect']>`	-

Returns

Returns Promise<TResult> where TResult is based on whether relations are included.

Example

// Find todos matching ANY of the criteria (OR condition)
const todos = await todosService.findByMatching({
  status: 'done',
  priority: 'high'
})

// All returned todos match AT LEAST ONE criteria
todos.forEach(todo => {
  const reason = todo.status === 'done' ? 'completed' : 'high priority'
  console.log(`${todo.title} - Found because: ${reason}`)
})

findByField()

Finds entities by a specific field and its value.

Parameters

Prop	Type	Default
`opts?`	`QueryOpts<T, TResult, TRels>`	-
`value`	`T['$inferSelect'][K]`	-
`field`	`keyof T['$inferSelect']`	-

Returns

Returns Promise<TResult> where TResult is based on whether relations are included.

Example

// Find all completed todos
const doneTodos = await todosService.findByField('status', 'done')
console.log(`Found ${doneTodos.length} completed todos`)

// Find todos by priority
const highPriorityTodos = await todosService.findByField('priority', 'high')
highPriorityTodos.forEach(todo => {
  console.log(`High priority: ${todo.title}`)
})

count()

Counts the number of entities that match the specified criteria.

Parameters

Prop	Type	Default
`opts?`	`QueryOpts<T, number>`	-
`criteria?`	`Partial<T['$inferSelect']>`	-

Returns

Returns Promise<number> - the count of matching entities.

Example

// Count all todos
const totalCount = await todosService.count()
console.log(`Total todos: ${totalCount}`)

// Count by criteria
const highPriorityCount = await todosService.count({ priority: 'high' })
const lowPriorityCount = await todosService.count({ priority: 'low' })
const mediumPriorityCount = await todosService.count({ priority: 'medium' })

console.log(`High: ${highPriorityCount}, Medium: ${mediumPriorityCount}, Low: ${lowPriorityCount}`)

// Count completed todos
const doneTasksCount = await todosService.count({ status: 'done' })
console.log(`Completed tasks: ${doneTasksCount}`)

findWithCursor()

Performs cursor-based pagination to retrieve entities. Useful for efficient pagination through large datasets.

Parameters

Prop	Type	Default
`opts`	`QueryOpts<T, TResult, TRels>`	-

Returns

Returns Promise<PaginationResult<T>> containing:

items: Array of entities
nextCursor: Cursor for next page (null if no more pages)
pagination: Metadata with page info, total count, and navigation flags

Example

// First page with cursor pagination
const firstPage = await todosService.findWithCursor({
  limit: 3,
  orderBy: { createdAt: 'desc' }
})

console.log(`Page 1: ${firstPage.items.length} items`)
console.log(`Total: ${firstPage.pagination.total}`)
console.log(`Has next: ${firstPage.pagination.hasNext}`)

// Get second page if available
if (firstPage.nextCursor) {
  const secondPage = await todosService.findWithCursor({
    limit: 3,
    cursor: firstPage.nextCursor,
    orderBy: { createdAt: 'desc' }
  })
  
  console.log(`Page 2: ${secondPage.items.length} items`)
  console.log(`Page number: ${secondPage.pagination.page}`)
}

filter()

Performs advanced filtering using Business Central style filter expressions with operators like ranges, wildcards, and comparisons.

Parameters

Prop	Type	Default
`opts?`	`QueryOpts<T, TResult, TRels>`	-
`criteria`	`FilterCriteria<T>`	-

Returns

Returns Promise<TResult> where TResult is based on whether relations are included.

Filter Expression Format

Filter expressions use the format: [filterExpression, ...values]

Range: ['%1..%2', 1000, 5000] - Between 1000 and 5000
Wildcard: ['*%1*', 'search'] - Contains 'search'
Multiple values: ['%1|%2|%3', 'A', 'B', 'C'] - Equals A, B, or C
Comparison: ['>%1', 100] - Greater than 100
Case insensitive: ['@*%1*', 'Search'] - Contains 'Search' (case insensitive)

Example

// Range filtering (example shown for reference)
const rangeFilteredTodos = await todosService.filter({
  // Note: Actual filter implementation may vary based on field types
  priority: ['%1|%2', 'high', 'medium'] // High or medium priority
})

console.log(`Found ${rangeFilteredTodos.length} high/medium priority todos`)

QueryOpts<T>

Common options available for most query operations.

Prop	Type	Default
`parse?`	`(data: any[]) => TResult`	-
`custom?`	`SQL`	-
`workspace?`	`{ field: keyof T['$inferSelect']; value: any }`	-
`relations?`	`TRels`	-
`cursor?`	`Date \| null`	-
`withDeleted?`	`boolean`	-
`orderBy?`	`{ [P in keyof T['$inferSelect']]?: 'asc' \| 'desc' }`	-
`limit?`	`number`	-
`page?`	`number`	-

Query Options Example

const todos = await todosService.findAll({
  page: 1,
  limit: 20,
  orderBy: { 
    priority: 'desc',
    createdAt: 'asc'
  },
  workspace: {
    field: 'tenant',
    value: 'company-abc'
  }
})

API Reference

On this page