tessl/npm-objection

An SQL-friendly ORM for Node.js built on Knex.js with powerful query building, relationship handling, and JSON Schema validation

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Query Building

Name: tessl/npm-objection
Author: tessl

Advanced query building with chainable methods, joins, aggregates, and complex WHERE conditions.

Capabilities

QueryBuilderBase Class

Base class providing core query building functionality and transaction support.

/**
 * Base QueryBuilder class providing core functionality
 */
class QueryBuilderBase {
  /**
   * Modify the query using a function or named modifier
   * @param func - Modifier function or name
   * @param args - Additional arguments for the modifier
   * @returns QueryBuilderBase instance
   */
  modify(func: string | Function, ...args: any[]): QueryBuilderBase;
  
  /**
   * Set transaction context for the query
   * @param trx - Knex transaction object or null
   * @returns QueryBuilderBase instance
   */
  transacting(trx: Transaction | null): QueryBuilderBase;
  
  /**
   * Clone the query builder
   * @returns New QueryBuilderBase instance
   */
  clone(): QueryBuilderBase;
  
  /**
   * Get the Knex query builder instance
   * @returns Knex QueryBuilder
   */
  knex(): Knex;
  
  /**
   * Convert to Knex query
   * @returns Knex QueryBuilder
   */
  toKnexQuery(): Knex.QueryBuilder;
  
  /**
   * Set query context
   * @param context - Context object
   * @returns QueryBuilderBase instance
   */
  context(context: object): QueryBuilderBase;
  
  /**
   * Clear query context
   * @returns QueryBuilderBase instance
   */
  clearContext(): QueryBuilderBase;
  
  /**
   * Enable query debugging
   * @returns QueryBuilderBase instance
   */
  debug(): QueryBuilderBase;
}

QueryBuilderOperation Class

Base class for query operations that modify the query builder.

/**
 * Base class for all query builder operations
 */
class QueryBuilderOperation {
  /**
   * Operation name
   */
  readonly name: string;
  
  /**
   * Operation constructor
   * @param name - Operation name
   * @param opt - Operation options
   */
  constructor(name: string, opt?: any);
  
  /**
   * Check if operation is a subclass of another operation
   * @param OperationClass - Operation class to check against
   * @returns boolean
   */
  is(OperationClass: Function): boolean;
  
  /**
   * Called when operation is added to query
   * @param builder - Query builder instance
   * @param args - Operation arguments
   * @returns QueryBuilderOperation instance
   */
  onAdd(builder: QueryBuilderBase, args: any[]): QueryBuilderOperation;
  
  /**
   * Called before build phase
   * @param builder - Query builder instance
   * @returns QueryBuilderOperation instance or Promise
   */
  onBefore1(builder: QueryBuilderBase): QueryBuilderOperation | Promise<QueryBuilderOperation>;
  
  /**
   * Called during build phase
   * @param builder - Query builder instance
   * @returns QueryBuilderOperation instance or Promise
   */
  onBuild(builder: QueryBuilderBase): QueryBuilderOperation | Promise<QueryBuilderOperation>;
  
  /**
   * Check if operation can be skipped
   * @param builder - Query builder instance
   * @returns boolean
   */
  hasOnBuild(builder: QueryBuilderBase): boolean;
  
  /**
   * Clone the operation
   * @param props - Properties to override
   * @returns New QueryBuilderOperation instance
   */
  clone(props?: object): QueryBuilderOperation;
}

QueryBuilder Class

Main query builder class providing chainable query methods for database operations.

/**
 * Main QueryBuilder class for constructing database queries
 */
class QueryBuilder {
  // Selection methods
  select(...columns: string[]): QueryBuilder;
  distinct(...columns: string[]): QueryBuilder;
  
  // FROM clause
  from(table: string | QueryBuilder): QueryBuilder;
  
  // WHERE conditions
  where(column: string, operator: string, value: any): QueryBuilder;
  where(column: string, value: any): QueryBuilder;
  where(object: object): QueryBuilder;
  where(callback: (builder: QueryBuilder) => void): QueryBuilder;
  
  orWhere(column: string, operator: string, value: any): QueryBuilder;
  whereNot(column: string, operator: string, value: any): QueryBuilder;
  whereIn(column: string, values: any[]): QueryBuilder;
  whereNotIn(column: string, values: any[]): QueryBuilder;
  whereNull(column: string): QueryBuilder;
  whereNotNull(column: string): QueryBuilder;
  whereBetween(column: string, range: [any, any]): QueryBuilder;
  whereExists(callback: (builder: QueryBuilder) => void): QueryBuilder;
  
  // Raw WHERE
  whereRaw(sql: string, ...bindings: any[]): QueryBuilder;
  orWhereRaw(sql: string, ...bindings: any[]): QueryBuilder;
  
  // JSON operations
  whereJsonObject(column: string, value: any): QueryBuilder;
  whereJsonPath(column: string, path: string, operator: string, value: any): QueryBuilder;
  whereJsonSupersetOf(column: string, value: any): QueryBuilder;
  whereJsonSubsetOf(column: string, value: any): QueryBuilder;
  
  // JOINS
  join(table: string, leftCol: string, rightCol: string): QueryBuilder;
  join(table: string, callback: (builder: JoinClause) => void): QueryBuilder;
  leftJoin(table: string, leftCol: string, rightCol: string): QueryBuilder;
  rightJoin(table: string, leftCol: string, rightCol: string): QueryBuilder;
  innerJoin(table: string, leftCol: string, rightCol: string): QueryBuilder;
  fullOuterJoin(table: string, leftCol: string, rightCol: string): QueryBuilder;
  
  // Relation joins
  joinRelated(expression: string, options?: JoinRelatedOptions): QueryBuilder;
  leftJoinRelated(expression: string, options?: JoinRelatedOptions): QueryBuilder;
  
  // ORDER BY
  orderBy(column: string, direction?: 'asc' | 'desc'): QueryBuilder;
  orderBy(columns: OrderByDescriptor[]): QueryBuilder;
  orderByRaw(sql: string, ...bindings: any[]): QueryBuilder;
  
  // GROUP BY
  groupBy(...columns: string[]): QueryBuilder;
  groupByRaw(sql: string, ...bindings: any[]): QueryBuilder;
  
  // HAVING
  having(column: string, operator: string, value: any): QueryBuilder;
  havingRaw(sql: string, ...bindings: any[]): QueryBuilder;
  
  // Aggregates
  count(column?: string): QueryBuilder;
  sum(column: string): QueryBuilder;
  avg(column: string): QueryBuilder;
  min(column: string): QueryBuilder;
  max(column: string): QueryBuilder;
  
  // Pagination
  limit(count: number): QueryBuilder;
  offset(count: number): QueryBuilder;
  page(page: number, pageSize: number): QueryBuilder;
  range(start?: number, end?: number): QueryBuilder;
  
  // CRUD operations
  insert(data: object | object[]): QueryBuilder;
  insertAndFetch(data: object | object[]): QueryBuilder;
  update(data: object): QueryBuilder;
  updateAndFetch(data: object): QueryBuilder;
  patch(data: object): QueryBuilder;
  patchAndFetch(data: object): QueryBuilder;
  delete(): QueryBuilder;
  del(): QueryBuilder;
  
  // Upsert operations
  onConflict(column?: string | string[]): QueryBuilder;
  merge(data?: object | string[]): QueryBuilder;
  ignore(): QueryBuilder;
  
  // Relations
  withGraphFetched(expression: string, options?: GraphOptions): QueryBuilder;
  withGraphJoined(expression: string, options?: GraphOptions): QueryBuilder;
  
  // Finders
  findById(id: any): QueryBuilder;
  findByIds(ids: any[]): QueryBuilder;
  findOne(...args: any[]): QueryBuilder;
  
  // Query execution
  execute(): Promise<any>;
  then(onFulfilled?: Function, onRejected?: Function): Promise<any>;
  
  // Query introspection
  isFind(): boolean;
  isInsert(): boolean;
  isUpdate(): boolean;
  isDelete(): boolean;
  
  // Query modification
  modify(modifier: string | Function, ...args: any[]): QueryBuilder;
  modifiers(modifiers: object): QueryBuilder;
  
  // Context
  context(context: object): QueryBuilder;
  clearContext(): QueryBuilder;
  
  // Utilities
  clone(): QueryBuilder;
  debug(): QueryBuilder;
  timeout(ms: number): QueryBuilder;
  returning(columns: string | string[]): QueryBuilder;
  
  // Knex integration
  toKnexQuery(): Knex.QueryBuilder;
  knex(): Knex;
}

Usage Examples:

const { Model } = require('objection');

// Basic SELECT query
const people = await Person.query()
  .select('firstName', 'lastName', 'age')
  .where('age', '>', 18)
  .orderBy('lastName');

// Complex WHERE conditions
const results = await Person.query()
  .where('age', '>=', 18)
  .where('active', true)
  .orWhere(builder => {
    builder.where('vip', true).where('age', '>=', 16);
  })
  .whereIn('category', ['premium', 'gold'])
  .whereNotNull('email');

// JOIN queries
const peopleWithPets = await Person.query()
  .join('pets', 'persons.id', 'pets.ownerId')
  .select('persons.*', 'pets.name as petName')
  .where('pets.species', 'dog');

// Aggregation
const stats = await Person.query()
  .groupBy('department')
  .select('department')
  .count('id as personCount')
  .avg('age as averageAge')
  .having('personCount', '>', 5);

Selection Methods

Methods for specifying which columns to select.

/**
 * Select specific columns
 * @param columns - Column names to select
 * @returns QueryBuilder instance
 */
select(...columns: string[]): QueryBuilder;

/**
 * Select distinct values
 * @param columns - Column names for distinct selection
 * @returns QueryBuilder instance
 */
distinct(...columns: string[]): QueryBuilder;

/**
 * Add columns to existing selection
 * @param columns - Additional column names
 * @returns QueryBuilder instance
 */
columns(...columns: string[]): QueryBuilder;

WHERE Conditions

Methods for adding WHERE conditions to queries.

/**
 * Add WHERE condition
 * @param column - Column name or object with conditions
 * @param operator - Comparison operator
 * @param value - Value to compare against
 * @returns QueryBuilder instance
 */
where(column: string, operator: string, value: any): QueryBuilder;
where(column: string, value: any): QueryBuilder;
where(conditions: object): QueryBuilder;

/**
 * Add OR WHERE condition
 */
orWhere(column: string, operator: string, value: any): QueryBuilder;

/**
 * Add WHERE NOT condition
 */
whereNot(column: string, operator: string, value: any): QueryBuilder;

/**
 * Add WHERE IN condition
 */
whereIn(column: string, values: any[]): QueryBuilder;

/**
 * Add WHERE NULL condition
 */
whereNull(column: string): QueryBuilder;

/**
 * Add WHERE BETWEEN condition
 */
whereBetween(column: string, range: [any, any]): QueryBuilder;

/**
 * Add raw WHERE condition
 */
whereRaw(sql: string, ...bindings: any[]): QueryBuilder;

JOIN Operations

Methods for joining tables.

/**
 * Add INNER JOIN
 * @param table - Table to join
 * @param leftCol - Left column for join condition
 * @param rightCol - Right column for join condition
 * @returns QueryBuilder instance
 */
join(table: string, leftCol: string, rightCol: string): QueryBuilder;

/**
 * Add LEFT JOIN
 */
leftJoin(table: string, leftCol: string, rightCol: string): QueryBuilder;

/**
 * Add RIGHT JOIN
 */
rightJoin(table: string, leftCol: string, rightCol: string): QueryBuilder;

/**
 * Join related models through relationship definitions
 * @param expression - Relation expression string
 * @param options - Join options
 * @returns QueryBuilder instance
 */
joinRelated(expression: string, options?: JoinRelatedOptions): QueryBuilder;

CRUD Operations

Methods for inserting, updating, and deleting data.

/**
 * Insert new records
 * @param data - Data to insert (object or array of objects)
 * @returns QueryBuilder instance
 */
insert(data: object | object[]): QueryBuilder;

/**
 * Insert and return the inserted records
 * @param data - Data to insert
 * @returns QueryBuilder instance
 */
insertAndFetch(data: object | object[]): QueryBuilder;

/**
 * Update existing records
 * @param data - Data to update
 * @returns QueryBuilder instance
 */
update(data: object): QueryBuilder;

/**
 * Update and return the updated records
 * @param data - Data to update
 * @returns QueryBuilder instance
 */
updateAndFetch(data: object): QueryBuilder;

/**
 * Patch (partial update) existing records
 * @param data - Data to patch
 * @returns QueryBuilder instance
 */
patch(data: object): QueryBuilder;

/**
 * Delete records
 * @returns QueryBuilder instance
 */
delete(): QueryBuilder;

Aggregation Methods

Methods for aggregate functions.

/**
 * Count records
 * @param column - Column to count (default: '*')
 * @returns QueryBuilder instance
 */
count(column?: string): QueryBuilder;

/**
 * Sum column values
 * @param column - Column to sum
 * @returns QueryBuilder instance
 */
sum(column: string): QueryBuilder;

/**
 * Average column values
 * @param column - Column to average
 * @returns QueryBuilder instance
 */
avg(column: string): QueryBuilder;

/**
 * Minimum column value
 * @param column - Column to find minimum
 * @returns QueryBuilder instance
 */
min(column: string): QueryBuilder;

/**
 * Maximum column value
 * @param column - Column to find maximum
 * @returns QueryBuilder instance
 */
max(column: string): QueryBuilder;

Types

interface JoinRelatedOptions {
  alias?: string | boolean;
  aliases?: Record<string, string>;
}

interface OrderByDescriptor {
  column: string;
  order?: 'asc' | 'desc';
}

interface GraphOptions {
  minimize?: boolean;
  separator?: string;
  aliases?: Record<string, string>;
  joinOperation?: string;
  maxBatchSize?: number;
}

interface JoinClause {
  on(leftCol: string, rightCol: string): JoinClause;
  onIn(leftCol: string, values: any[]): JoinClause;
  onNull(column: string): JoinClause;
  onNotNull(column: string): JoinClause;
  using(columns: string[]): JoinClause;
}

Install with Tessl CLI