@adonisjs/lucid

@adonisjs/lucid

Version 18.4.0
Published 10 days ago
1 MB
13 dependencies
MIT license

Install

npm i @adonisjs/lucid

yarn add @adonisjs/lucid

pnpm add @adonisjs/lucid

Overview

SQL ORM built on top of Active Record pattern

Index

Namespaces

@ioc:Adonis/Core/Application
- ContainerBindings
@ioc:Adonis/Core/Event
- EventsList
@ioc:Adonis/Core/TestUtils
@ioc:Adonis/Core/Validator
- DbRowCheckOptions
- Rules
@ioc:Adonis/Lucid/Database
@ioc:Adonis/Lucid/Factory
@ioc:Adonis/Lucid/Migrator
@ioc:Adonis/Lucid/Orm
@ioc:Adonis/Lucid/Schema
@ioc:Adonis/Lucid/Seeder

Namespaces

namespace @ioc:Adonis/Core/Application

module '@ioc:Adonis/Core/Application' {}

interface ContainerBindings

interface ContainerBindings {}

property 'Adonis/Lucid/Database'

'Adonis/Lucid/Database': DatabaseContract;

property 'Adonis/Lucid/Factory'

'Adonis/Lucid/Factory': FactoryManagerContract;

property 'Adonis/Lucid/Migrator'

'Adonis/Lucid/Migrator': typeof Migrator;

property 'Adonis/Lucid/Orm'

'Adonis/Lucid/Orm': typeof Orm;

property 'Adonis/Lucid/Schema'

'Adonis/Lucid/Schema': SchemaConstructorContract;

property 'Adonis/Lucid/Seeder'

'Adonis/Lucid/Seeder': SeederConstructorContract;

namespace @ioc:Adonis/Core/Event

module '@ioc:Adonis/Core/Event' {}

interface EventsList

interface EventsList {}

property 'db:query'

'db:query': DbQueryEventNode;

namespace @ioc:Adonis/Core/TestUtils

module '@ioc:Adonis/Core/TestUtils' {}

interface TestUtilsContract

interface TestUtilsContract {}

method db

db: (connectionName?: string) => {
    seed: HookCallback;
    migrate: HookCallback;
    truncate: HookCallback;
};

type HookCallback

type HookCallback = () => Promise<HookCleanupHandler> | Promise<void>;

type HookCleanupHandler

type HookCleanupHandler = () => Promise<void>;

namespace @ioc:Adonis/Core/Validator

module '@ioc:Adonis/Core/Validator' {}

interface Rules

interface Rules {}

method exists

exists: (options: DbRowCheckOptions) => Rule;

method unique

unique: (options: DbRowCheckOptions) => Rule;

type DbRowCheckOptions

type DbRowCheckOptions = {
    table: string;
    column: string;
    dateFormat?: string;
    connection?: string;
    caseInsensitive?: boolean;
    constraints?: {
        [key: string]: any;
    };
    where?: {
        [key: string]: any;
    };
    whereNot?: {
        [key: string]: any;
    };
};

namespace @ioc:Adonis/Lucid/Database

module '@ioc:Adonis/Lucid/Database' {}

interface Aggregate

interface Aggregate<Builder extends ChainableContract> {}

Possible signatures for aggregate functions. Aggregates will push to the result set. Unlike knex, we force defining aliases for each aggregate.

call signature

(column: OneOrMany<ValueWithSubQueries<string>>, alias?: string): Builder;

Accepting column with the alias for the count.

call signature

(columns: Dictionary<OneOrMany<ValueWithSubQueries<string>>, string>): Builder;

Accepting an object for multiple counts in a single query.

interface ChainableContract

interface ChainableContract {}

The chainable contract has all the methods that can be chained to build a query. This interface will never have any methods to execute a query.

property andHaving

andHaving: Having<this>;

property andHavingBetween

andHavingBetween: HavingBetween<this>;

property andHavingExists

andHavingExists: HavingExists<this>;

property andHavingIn

andHavingIn: HavingIn<this>;

property andHavingNotBetween

andHavingNotBetween: HavingBetween<this>;

property andHavingNotExists

andHavingNotExists: HavingExists<this>;

property andHavingNotIn

andHavingNotIn: HavingIn<this>;

property andHavingNotNull

andHavingNotNull: HavingNull<this>;

property andHavingNull

andHavingNull: HavingNull<this>;

property andHavingRaw

andHavingRaw: RawQueryFn<this>;

property andWhere

andWhere: Where<this>;

property andWhereBetween

andWhereBetween: WhereBetween<this>;

property andWhereColumn

andWhereColumn: WhereColumn<this>;

property andWhereExists

andWhereExists: WhereExists<this>;

property andWhereILike

andWhereILike: WhereLike<this>;

property andWhereIn

andWhereIn: WhereIn<this>;

property andWhereJson

andWhereJson: WhereJson<this>;

property andWhereJsonPath

andWhereJsonPath: WhereJsonPath<this>;

property andWhereJsonSubset

andWhereJsonSubset: WhereJson<this>;

property andWhereJsonSuperset

andWhereJsonSuperset: WhereJson<this>;

property andWhereLike

andWhereLike: WhereLike<this>;

property andWhereNot

andWhereNot: Where<this>;

property andWhereNotBetween

andWhereNotBetween: WhereBetween<this>;

property andWhereNotColumn

andWhereNotColumn: WhereColumn<this>;

property andWhereNotExists

andWhereNotExists: WhereExists<this>;

property andWhereNotIn

andWhereNotIn: WhereIn<this>;

property andWhereNotJson

andWhereNotJson: WhereJson<this>;

property andWhereNotJsonSubset

andWhereNotJsonSubset: WhereJson<this>;

property andWhereNotJsonSuperset

andWhereNotJsonSuperset: WhereJson<this>;

property andWhereNotNull

andWhereNotNull: WhereNull<this>;

property andWhereNull

andWhereNull: WhereNull<this>;

property andWhereRaw

andWhereRaw: RawQueryFn<this>;

property columns

columns: (string | Knex.QueryBuilder | Knex.RawQueryBuilder)[];

property crossJoin

crossJoin: Join<this>;

property distinct

distinct: Distinct<this>;

property distinctOn

distinctOn: Distinct<this>;

property from

from: FromTable<this>;

property fullOuterJoin

fullOuterJoin: Join<this>;

property groupBy

groupBy: GroupBy<this>;

property groupByRaw

groupByRaw: RawQueryFn<this>;

property hasAggregates

hasAggregates: boolean;

property hasGroupBy

hasGroupBy: boolean;

property hasUnion

hasUnion: boolean;

property having

having: Having<this>;

property havingBetween

havingBetween: HavingBetween<this>;

property havingExists

havingExists: HavingExists<this>;

property havingIn

havingIn: HavingIn<this>;

property havingNotBetween

havingNotBetween: HavingBetween<this>;

property havingNotExists

havingNotExists: HavingExists<this>;

property havingNotIn

havingNotIn: HavingIn<this>;

property havingNotNull

havingNotNull: HavingNull<this>;

property havingNull

havingNull: HavingNull<this>;

property havingRaw

havingRaw: RawQueryFn<this>;

property innerJoin

innerJoin: Join<this>;

property intersect

intersect: Intersect<this>;

property join

join: Join<this>;

property joinRaw

joinRaw: RawQueryFn<this>;

property keysResolver

keysResolver?: (columnName: string) => string;

property knexQuery

knexQuery: Knex.QueryBuilder;

property leftJoin

leftJoin: Join<this>;

property leftOuterJoin

leftOuterJoin: Join<this>;

property orderBy

orderBy: OrderBy<this>;

property orderByRaw

orderByRaw: RawQueryFn<this>;

property orHaving

orHaving: Having<this>;

property orHavingBetween

orHavingBetween: HavingBetween<this>;

property orHavingExists

orHavingExists: HavingExists<this>;

property orHavingIn

orHavingIn: HavingIn<this>;

property orHavingNotBetween

orHavingNotBetween: HavingBetween<this>;

property orHavingNotExists

orHavingNotExists: HavingExists<this>;

property orHavingNotIn

orHavingNotIn: HavingIn<this>;

property orHavingNotNull

orHavingNotNull: HavingNull<this>;

property orHavingNull

orHavingNull: HavingNull<this>;

property orHavingRaw

orHavingRaw: RawQueryFn<this>;

property orWhere

orWhere: Where<this>;

property orWhereBetween

orWhereBetween: WhereBetween<this>;

property orWhereColumn

orWhereColumn: WhereColumn<this>;

property orWhereExists

orWhereExists: WhereExists<this>;

property orWhereILike

orWhereILike: WhereLike<this>;

property orWhereIn

orWhereIn: WhereIn<this>;

property orWhereJson

orWhereJson: WhereJson<this>;

property orWhereJsonPath

orWhereJsonPath: WhereJsonPath<this>;

property orWhereJsonSubset

orWhereJsonSubset: WhereJson<this>;

property orWhereJsonSuperset

orWhereJsonSuperset: WhereJson<this>;

property orWhereLike

orWhereLike: WhereLike<this>;

property orWhereNot

orWhereNot: Where<this>;

property orWhereNotBetween

orWhereNotBetween: WhereBetween<this>;

property orWhereNotColumn

orWhereNotColumn: WhereColumn<this>;

property orWhereNotExists

orWhereNotExists: WhereExists<this>;

property orWhereNotIn

orWhereNotIn: WhereIn<this>;

property orWhereNotJson

orWhereNotJson: WhereJson<this>;

property orWhereNotJsonSubset

orWhereNotJsonSubset: WhereJson<this>;

property orWhereNotJsonSuperset

orWhereNotJsonSuperset: WhereJson<this>;

property orWhereNotNull

orWhereNotNull: WhereNull<this>;

property orWhereNull

orWhereNull: WhereNull<this>;

property orWhereRaw

orWhereRaw: RawQueryFn<this>;

property rightJoin

rightJoin: Join<this>;

property rightOuterJoin

rightOuterJoin: Join<this>;

property select

select: DatabaseQueryBuilderSelect<this>;

property subQueryAlias

subQueryAlias?: string;

property union

union: Union<this>;

property unionAll

unionAll: UnionAll<this>;

property where

where: Where<this>;

property whereBetween

whereBetween: WhereBetween<this>;

property whereColumn

whereColumn: WhereColumn<this>;

property whereExists

whereExists: WhereExists<this>;

property whereILike

whereILike: WhereLike<this>;

property whereIn

whereIn: WhereIn<this>;

property whereJson

whereJson: WhereJson<this>;

property whereJsonPath

whereJsonPath: WhereJsonPath<this>;

property whereJsonSubset

whereJsonSubset: WhereJson<this>;

property whereJsonSuperset

whereJsonSuperset: WhereJson<this>;

property whereLike

whereLike: WhereLike<this>;

property whereNot

whereNot: Where<this>;

property whereNotBetween

whereNotBetween: WhereBetween<this>;

property whereNotColumn

whereNotColumn: WhereColumn<this>;

property whereNotExists

whereNotExists: WhereExists<this>;

property whereNotIn

whereNotIn: WhereIn<this>;

property whereNotJson

whereNotJson: WhereJson<this>;

property whereNotJsonSubset

whereNotJsonSubset: WhereJson<this>;

property whereNotJsonSuperset

whereNotJsonSuperset: WhereJson<this>;

property whereNotNull

whereNotNull: WhereNull<this>;

property whereNull

whereNull: WhereNull<this>;

property whereRaw

whereRaw: RawQueryFn<this>;

property with

with: With<this>;

property withMaterialized

withMaterialized: With<this>;

property withNotMaterialized

withNotMaterialized: With<this>;

property withRecursive

withRecursive: With<this>;

method as

as: (name: string) => this;

method clearHaving

clearHaving: () => this;

method clearLimit

clearLimit: () => this;

method clearOffset

clearOffset: () => this;

method clearOrder

clearOrder: () => this;

method clearSelect

clearSelect: () => this;

method clearWhere

clearWhere: () => this;

method forShare

forShare: (...tableNames: string[]) => this;

method forUpdate

forUpdate: (...tableNames: string[]) => this;

method if

if: (
    condition: any,
    matchCallback: (query: this) => any,
    noMatchCallback?: (query: this) => any
) => this;

Executes the callback when condition is truthy

method limit

limit: (limit: number) => this;

method match

match: (
    ...blocks: (
        | [condition: any, callback: (query: this) => any]
        | ((query: this) => any)
    )[]
) => this;

Write blocks to match from

method noWait

noWait: () => this;

method offset

offset: (offset: number) => this;

method skipLocked

skipLocked: () => this;

method unless

unless: (
    condition: any,
    matchCallback: (query: this) => any,
    noMatchCallback?: (query: this) => any
) => this;

Executes the callback when condition is falsy

method withSchema

withSchema: (schema: string) => this;

method wrapExisting

wrapExisting: () => this;

interface Counter

interface Counter<Builder extends ChainableContract> {}

Possible signatures for incrementing/decrementing values

call signature

(column: string, counter?: number): Builder;

call signature

(values: Dictionary<number, string>): Builder;

interface DatabaseQueryBuilderContract

interface DatabaseQueryBuilderContract<Result = Dictionary<any, string>>
    extends ChainableContract,
        ExcutableQueryBuilderContract<Result[]> {}

Database query builder exposes the API to construct SQL query using fluent chainable API

property avg

avg: Aggregate<this>;

property avgDistinct

avgDistinct: Aggregate<this>;

property client

client: QueryClientContract;

property count

count: Aggregate<this>;

Aggregates

property countDistinct

countDistinct: Aggregate<this>;

property decrement

decrement: Counter<this>;

property increment

increment: Counter<this>;

property max

max: Aggregate<this>;

property min

min: Aggregate<this>;

property returning

returning: Returning<this>;

property sum

sum: Aggregate<this>;

property sumDistinct

sumDistinct: Aggregate<this>;

property update

update: Update<this>;

Mutations (update and increment can be one query aswell)

method clone

clone: <ClonedResult = Result>() => DatabaseQueryBuilderContract<ClonedResult>;

Clone current query

method del

del: (returning?: OneOrMany<string>) => this;

Perform delete operation

method delete

delete: (returning?: OneOrMany<string>) => this;

method first

first: () => Promise<Result | null>;

Execute and get first result

method firstOrFail

firstOrFail: () => Promise<Result>;

Execute and get first result or fail

method forPage

forPage: (page: number, perPage?: number) => this;

A shorthand to define limit and offset based upon the current page

method ifDialect

ifDialect: (
    dialect: DialectContract['name'] | DialectContract['name'][],
    matchCallback: (query: this) => any,
    noMatchCallback?: (query: this) => any
) => this;

Executes the callback when dialect matches one of the mentioned dialects

method paginate

paginate: (
    page: number,
    perPage?: number
) => Promise<SimplePaginatorContract<Result>>;

Execute query with pagination

method unlessDialect

unlessDialect: (
    dialect: DialectContract['name'] | DialectContract['name'][],
    matchCallback: (query: this) => any,
    noMatchCallback?: (query: this) => any
) => this;

Executes the callback when dialect matches doesn't all the mentioned dialects

interface DatabaseQueryBuilderSelect

interface DatabaseQueryBuilderSelect<Builder extends ChainableContract> {}

Possible signatures for a select method on database query builder.

call signature

(columns: Dictionary<string, string>): Builder;

Selecting columns as a dictionary with key as the alias and value is the original column.

call signature

(columns: ValueWithSubQueries<string | number>[]): Builder;

An array of values with subqueries

call signature

(...columns: ValueWithSubQueries<string | number>[]): Builder;

A spread of array arguments

call signature

(column: '*'): Builder;

Wildcard selector.

interface Distinct

interface Distinct<Builder extends ChainableContract> {}

Possible signatures for a distinct clause

call signature

(columns: string[]): Builder;

call signature

(...columns: string[]): Builder;

call signature

(column: '*'): Builder;

interface ExcutableQueryBuilderContract

interface ExcutableQueryBuilderContract<Result> extends Promise<Result> {}

A executable query builder will always have these methods on it.

method debug

debug: (debug: boolean) => this;

method exec

exec: () => Promise<Result>;

method reporterData

reporterData: (data: any) => this;

method timeout

timeout: (time: number, options?: { cancel: boolean }) => this;

method toQuery

toQuery: () => string;

method toSQL

toSQL: () => Knex.Sql;

method useTransaction

useTransaction: (trx: TransactionClientContract) => this;

interface FromTable

interface FromTable<Builder extends ChainableContract> {}

Possible signatures for defining table for a select query.

call signature

(
    table:
        | string
        | Dictionary<string, string>
        | QueryCallback<Builder>
        | ChainableContract
): Builder;

interface GroupBy

interface GroupBy<Builder extends ChainableContract> extends Distinct<Builder> {}

The signatures are same as the distinct method. For subqueries and raw queries, one must use groupByRaw.

interface Having

interface Having<Builder extends ChainableContract> {}

Possible signatures for having clause

call signature

(callback: QueryCallback<Builder> | RawBuilderContract | RawQuery): Builder;

A subquery callback

call signature

(
    key: string | RawQuery,
    operator: string,
    value: StrictValues | ChainableContract | RawBuilderContract | RawQuery
): Builder;

Key operator and value. Value can be a subquery as well

interface HavingBetween

interface HavingBetween<Builder extends ChainableContract>
    extends WhereBetween<Builder> {}

Possible signatures for having between

interface HavingExists

interface HavingExists<Builder extends ChainableContract> {}

Possible signatures for having exists clause

call signature

(callback: QueryCallback<Builder> | ChainableContract): Builder;

A query callback or a sub query

interface HavingIn

interface HavingIn<Builder extends ChainableContract> {}

Possible signatures for having in clause.

call signature

(
    key: string | RawQuery,
    value: (StrictValues | ChainableContract | RawBuilderContract | RawQuery)[]
): Builder;

Key and an array of literal values, raw queries or subqueries.

call signature

(key: string | RawQuery, callback: QueryCallback<Builder>): Builder;

Key, along with a query callback

interface HavingNull

interface HavingNull<Builder extends ChainableContract> extends WhereNull<Builder> {}

Possible signatures for having null clause

interface Insert

interface Insert<Builder extends InsertQueryBuilderContract> {}

Possible signatures for an insert query

call signature

(values: Dictionary<any, string>): Builder;

interface InsertQueryBuilderContract

interface InsertQueryBuilderContract<Result = any>
    extends ExcutableQueryBuilderContract<Result> {}

Insert query builder to perform database inserts.

property client

client: QueryClientContract;

property insert

insert: Insert<this>;

Inserting a single record.

property knexQuery

knexQuery: Knex.QueryBuilder;

property multiInsert

multiInsert: MultiInsert<this>;

Inserting multiple columns at once

property returning

returning: Returning<this>;

Define returning columns

method table

table: (table: string) => this;

Table for the insert query

method withSchema

withSchema: (schema: string) => this;

interface Intersect

interface Intersect<Builder extends ChainableContract> extends Union<Builder> {}

Same signature as union

interface Join

interface Join<Builder extends ChainableContract> {}

Possible signatures for join query

call signature

(table: string, primaryColumn: string, secondaryColumn: string): Builder;

Defining the join table with primary and secondary columns to match

call signature

(table: string, primaryColumn: string, raw: RawQuery): Builder;

Defining the join table with primary and secondary columns to match, where secondary column is output of a raw query

call signature

(
    table: string,
    primaryColumn: string,
    operator: string,
    secondaryColumn: string
): Builder;

Defining the join table with primary and secondary columns to match with a custom operator

call signature

(table: string, callback: Knex.JoinCallback): Builder;

Join with a callback. The callback receives an array of join class from knex directly.

interface MultiInsert

interface MultiInsert<Builder extends InsertQueryBuilderContract> {}

Possible signatures for doing multiple inserts in a single query

call signature

(values: Dictionary<any, string>[]): Builder;

interface OrderBy

interface OrderBy<Builder extends ChainableContract> {}

Possible signatures for orderBy method.

call signature

(
    column: string | ChainableContract | RawBuilderContract | RawQuery,
    direction?: 'asc' | 'desc'
): Builder;

Order by a column and optional direction

call signature

(columns: string[]): Builder;

Order by multiple columns in default direction

call signature

(
    columns: {
        column: string | ChainableContract | RawBuilderContract | RawQuery;
        order?: 'asc' | 'desc';
    }[]
): Builder;

Order by multiple columns and custom direction for each of them

interface RawBuilderContract

interface RawBuilderContract {}

Static raw builder

method toKnex

toKnex: (client: Knex.Client) => Knex.Raw;

method wrap

wrap: (before: string, after: string) => this;

interface RawQueryBuilderContract

interface RawQueryBuilderContract<Result = any>
    extends ExcutableQueryBuilderContract<Result> {}

Shape of the raw query that can also be passed as a value to other queries

property client

client: QueryClientContract;

property knexQuery

knexQuery: Knex.Raw;

method wrap

wrap: (before: string, after: string) => this;

interface RawQueryFn

interface RawQueryFn<Builder extends ChainableContract> {}

A builder method to allow raw queries. However, the return type is the instance of current query builder. This is used for .{verb}Raw methods.

call signature

(sql: string | RawQuery): Builder;

call signature

(sql: string, bindings: RawQueryBindings): Builder;

interface ReferenceBuilderContract

interface ReferenceBuilderContract {}

Reference builder

method as

as: (name: string) => this;

method toKnex

toKnex: (client: Knex.Client) => Knex.Ref<string, any>;

method withSchema

withSchema: (name: string) => this;

interface Returning

interface Returning<Builder> {}

Possible signatures for the returning method.

call signature

(column: OneOrMany<string>): Builder;

interface SimplePaginatorContract

interface SimplePaginatorContract<Result> extends Array<Result> {}

Shape of the simple paginator that works with offset and limit

property currentPage

readonly currentPage: number;

property firstPage

readonly firstPage: number;

property hasMorePages

readonly hasMorePages: boolean;

property hasPages

readonly hasPages: boolean;

property hasTotal

readonly hasTotal: boolean;

property isEmpty

readonly isEmpty: boolean;

property lastPage

readonly lastPage: number;

property namingStrategy

namingStrategy: {
    paginationMetaKeys(): SimplePaginatorMetaKeys;
};

property perPage

readonly perPage: number;

property total

readonly total: number;

method all

all: () => Result[];

method baseUrl

baseUrl: (url: string) => this;

method getMeta

getMeta: () => any;

method getNextPageUrl

getNextPageUrl: () => string | null;

method getPreviousPageUrl

getPreviousPageUrl: () => string | null;

method getUrl

getUrl: (page: number) => string;

method getUrlsForRange

getUrlsForRange: (
    start: number,
    end: number
) => { url: string; page: number; isActive: boolean }[];

method queryString

queryString: (values: { [key: string]: any }) => this;

method toJSON

toJSON: () => { meta: any; data: Result[] };

interface Union

interface Union<Builder extends ChainableContract> {}

Possible signatures for a union clause

call signature

(callback: OneOrMany<QueryCallback<Builder>>, wrap?: boolean): Builder;

call signature

(subquery: OneOrMany<ChainableContract | RawQuery>, wrap?: boolean): Builder;

interface UnionAll

interface UnionAll<Builder extends ChainableContract> extends Union<Builder> {}

Same signature as union

interface Update

interface Update<Builder extends ChainableContract> {}

Possible signatures for performing an update

call signature

(values: Dictionary<any, string>, returning?: OneOrMany<string>): Builder;

Accepts an array of object of named key/value pair and returns an array of Generic return columns.

call signature

(column: string, value: any, returning?: OneOrMany<string>): Builder;

Accepts a key-value pair to update.

interface Where

interface Where<Builder extends ChainableContract> {}

Possible signatures for adding a where clause

call signature

(callback: QueryCallback<Builder>): Builder;

Callback for wrapped clauses

call signature

(clause: Dictionary<any, string>): Builder;

Passing an object of named key-value pair

call signature

(key: string | RawQuery, value: StrictValues | ChainableContract): Builder;

Key-value pair. The value can also be a subquery

call signature

(
    key: string | RawQuery,
    operator: string,
    value: StrictValues | ChainableContract
): Builder;

interface WhereBetween

interface WhereBetween<Builder extends ChainableContract> {}

Possibles signatures for adding a where between clause

call signature

(
    key: string | RawQuery,
    value: [StrictValues | ChainableContract, StrictValues | ChainableContract]
): Builder;

Accept any string as a key for supporting prefix columns

interface WhereColumn

interface WhereColumn<Builder extends ChainableContract> {}

Possible signatures for adding a where column clause

call signature

(column: string | RawQuery, comparisonColumn: string): Builder;

Key-value pair.

call signature

(column: string | RawQuery, operator: string, comparisonColumn: string): Builder;

interface WhereExists

interface WhereExists<Builder extends ChainableContract> {}

Possibles signatures for adding a where exists clause

call signature

(
    callback:
        | QueryCallback<Builder>
        | ChainableContract
        | RawBuilderContract
        | RawQuery
): Builder;

interface WhereIn

interface WhereIn<Builder extends ChainableContract> {}

Possible signatures for adding where in clause.

call signature

(K: string | RawQuery, value: StrictValues[]): Builder;

Column name and array of values

call signature

(K: string[], value: StrictValues[][]): Builder;

Column names and array of values as an 2d array

call signature

(
    k: string | RawQuery,
    subquery:
        | ChainableContract
        | QueryCallback<Builder>
        | RawBuilderContract
        | RawQuery
): Builder;

Column name with a subquery for a callback that yields an array of results

call signature

(
    k: string[],
    subquery: ChainableContract | RawBuilderContract | RawQuery
): Builder;

Column names along with a subquery that yields an array

interface WhereJson

interface WhereJson<Builder extends ChainableContract> {}

Possible signatures for adding a whereLike clause

call signature

(
    column: string,
    value: Record<string, any> | ChainableContract | QueryCallback<Builder>
): Builder;

Key-value pair. The value can also be a subquery

interface WhereJsonPath

interface WhereJsonPath<Builder extends ChainableContract> {}

call signature

(
    column: string,
    jsonPath: string,
    value:
        | string
        | number
        | boolean
        | string[]
        | number[]
        | boolean[]
        | Record<string, any>
        | ChainableContract
        | QueryCallback<Builder>
): Builder;

call signature

(
    column: string,
    jsonPath: string,
    operator: string,
    value:
        | string
        | number
        | boolean
        | string[]
        | number[]
        | boolean[]
        | Record<string, any>
        | ChainableContract
        | QueryCallback<Builder>
): Builder;

interface WhereLike

interface WhereLike<Builder extends ChainableContract> {}

Possible signatures for adding a whereLike clause

call signature

(key: string, value: StrictValues | ChainableContract): Builder;

Key-value pair. The value can also be a subquery

interface WhereNull

interface WhereNull<Builder extends ChainableContract> {}

Possible signatures for adding whereNull clause.

call signature

(key: string | RawQuery): Builder;

interface With

interface With<Builder extends ChainableContract> {}

Possible signatures of with CTE

call signature

(
    alias: string,
    query: RawQuery | ChainableContract | QueryCallback<Builder>,
    columns?: string[]
): Builder;

type DBQueryCallback

type DBQueryCallback = (
    userFn: QueryCallback<ChainableContract>,
    keysResolver?: (columnName: string) => string
) => (builder: Knex.QueryBuilder) => void;

Shape of the function accepted by the chainable query builder to pass lucid query builder to wrapped callbacks like .where(function () {}).
- This method will accept the wrapped callback - Return a new method, that is accepted by Knex. - When knex calls that method, this method will invoke the user wrapped callback, but instead of passing the knex query builder, it will pass the appropriate lucid query builder.

type Dictionary

type Dictionary<T, K extends string | number = string> = {
    [key in K]: T;
};

Extracted from ts-essentials

type OneOrMany

type OneOrMany<T> = T | T[];

Get one or many of a generic

type QueryCallback

type QueryCallback<Builder> = (builder: Builder) => void;

Query callback is used to write wrapped queries. We get rid of this from knex, since it makes everything confusing.

type RawQuery

type RawQuery =
    | RawBuilderContract
    | RawQueryBuilderContract
    | Knex.Raw
    | Knex.RawQueryBuilder;

Acceptable raw queries

type RawQueryBindings

type RawQueryBindings =
    | {
          [key: string]: StrictValues;
      }
    | StrictValues[];

Shape of raw query bindings

type SimplePaginatorMetaKeys

type SimplePaginatorMetaKeys = {
    total: string;
    perPage: string;
    currentPage: string;
    lastPage: string;
    firstPage: string;
    firstPageUrl: string;
    lastPageUrl: string;
    nextPageUrl: string;
    previousPageUrl: string;
};

The keys for the simple paginator meta data

type StrictValues

type StrictValues =
    | string
    | number
    | boolean
    | Date
    | Array<string>
    | Array<number>
    | Array<Date>
    | Array<boolean>
    | Buffer
    | RawQuery
    | ReferenceBuilderContract;

A known set of values allowed when defining values for different clauses

type StrictValuesWithoutRaw

type StrictValuesWithoutRaw = Exclude<StrictValues, RawQuery>;

Strict set of allowed values except the raw queries

type ValueWithSubQueries

type ValueWithSubQueries<T> = T | ChainableContract | RawQuery;

Allowing a generic value along with raw query instance or a subquery instance

namespace @ioc:Adonis/Lucid/Factory

module '@ioc:Adonis/Lucid/Factory' {}

variable Factory

const Factory: FactoryManagerContract;

interface FactoryBuilderContract

interface FactoryBuilderContract<
    FactoryModel extends FactoryModelContract<LucidModel>
> {}

Factory builder uses the factory model to create/make instances of lucid models

property factory

factory: FactoryModel;

Reference to the factory

method apply

apply: <K extends keyof FactoryModel['states']>(...states: K[]) => this;

Apply pre-defined state

method client

client: (client: QueryClientContract) => this;

Define custom query client

method connection

connection: (connection: string) => this;

Define custom database connection

method create

create: () => Promise<InstanceType<FactoryModel['model']>>;

Create and persist model instance

method createMany

createMany: (count: number) => Promise<InstanceType<FactoryModel['model']>[]>;

Create and persist more than one model instance

method make

make: () => Promise<InstanceType<FactoryModel['model']>>;

Make model instance without persitance. The make method doesn't process relationships

method makeMany

makeMany: (count: number) => Promise<InstanceType<FactoryModel['model']>[]>;

Make model instance without persitance. The makeMany method doesn't process relationships

method makeStubbed

makeStubbed: () => Promise<InstanceType<FactoryModel['model']>>;

Create model instance and stub out the persistance mechanism

method makeStubbedMany

makeStubbedMany: (
    count: number
) => Promise<InstanceType<FactoryModel['model']>[]>;

Create one or more model instances and stub out the persistance mechanism.

method merge

merge: (attributes: OneOrMany<ExtractFactoryAttributes<FactoryModel>>) => this;

Merge custom set of attributes. They are passed to the merge method of the model factory
For createMany and makeMany, you can pass an array of attributes mapped according to the array index.

method mergeRecursive

mergeRecursive: (attributes: any) => this;

Merge custom set of attributes with the correct factory builder model and all of its relationships as well

method pivotAttributes

pivotAttributes: (attributes: ModelObject | ModelObject[]) => this;

Define pivot attributes when persisting a many to many relationship. Results in a noop, when not called for a many to many relationship

method tap

tap: (
    callback: (
        row: InstanceType<FactoryModel['model']>,
        ctx: FactoryContextContract,
        builder: this
    ) => void
) => this;

Tap into the persistence layer of factory builder. Allows one to modify the model instance just before it is persisted to the database

method useCtx

useCtx: (ctx: FactoryContextContract) => this;

Define custom runtime context. This method is usually called by the relationships to ensure a single context is used by the parent and relationship factories.
Do not define a custom context, unless you know what you are really doing.

method with

with: <K extends keyof FactoryModel['relations']>(
    relation: K,
    count?: number,
    callback?: (
        builder: FactoryModel['relations'][K] extends () => FactoryBuilderContract<any>
            ? ReturnType<FactoryModel['relations'][K]> & {
                  parent: InstanceType<FactoryModel['model']>;
              }
            : never
    ) => void
) => this;

Create/make relationships for explicitly defined related factories

interface FactoryBuilderQueryContract

interface FactoryBuilderQueryContract<
    FactoryModel extends FactoryModelContract<LucidModel>
> extends FactoryBuilderContract<FactoryModel> {}

Query contract that initiates the factory builder. Since the factory builder API surface is small, we also proxy all of it's methods for a nicer DX

method query

query: (
    options?: ModelAdapterOptions,
    viaRelation?: FactoryRelationContract
) => FactoryBuilderContract<FactoryModel>;

interface FactoryContextContract

interface FactoryContextContract {}

The runtime context of the factory builder. A new state is constructed for each create/make operation and passed down to relationships as well.

property $trx

$trx: TransactionClientContract | undefined;

property faker

faker: typeof faker;

property isStubbed

isStubbed: boolean;

interface FactoryManagerContract

interface FactoryManagerContract {}

Factory manager to define new factories

method define

define: <Model extends LucidModel>(
    model: Model,
    callback: DefineCallback<Model>
) => FactoryModelContract<Model>;

Define a custom factory

method stubId

stubId: (callback: StubIdCallback) => void;

Define a custom callback to generate stub ids

interface FactoryModelContract

interface FactoryModelContract<Model extends LucidModel> {}

Factory model exposes the API to defined a model factory with states and relationships

property model

model: Model;

Reference to the underlying lucid model used by the factory model

property relations

relations: unknown;

property states

states: unknown;

Mainly for types support. Not used at runtime to derive any logic. Sorry, at times have to hack into typescript to get the desired output. :)

method after

after: (event: EventsList, handler: HooksHandler<this>) => this;

Define after hooks.

method before

before: (
    event: Exclude<EventsList, 'make'>,
    handler: HooksHandler<this>
) => this;

Define before hooks. Only create event is invoked during the before lifecycle

method build

build: () => FactoryBuilderQueryContract<this>;

Build model factory. This method returns the factory builder, which can be used to execute model queries

method merge

merge: (callback: MergeCallback<this>) => this;

method newUp

newUp: (callback: NewUpCallback<this>) => this;

Optionally define a custom method to instantiate the model instance and manage merging attributes

method relation

relation: <K extends ExtractModelRelations<InstanceType<Model>>, Relation>(
    relation: K,
    callback: Relation
) => this & { relations: { [P in K]: Relation } };

Define a relationship on another factory

method state

state: <K extends string>(
    state: K,
    callback: StateCallback<Model>
) => this & { states: { [P in K]: StateCallback<Model> } };

Define custom state for the factory. When executing the factory, you can apply the pre-defined states

interface FactoryRelationContract

interface FactoryRelationContract {}

Shape of the factory relationships. To keep relationships slim, we will have a common interface for relationships vs fine tuning API for each type of relationship

property parent

parent: LucidRow;

property relation

relation: RelationshipsContract;

Reference to the Lucid model relationship

method create

create: (
    parent: LucidRow,
    callback?: RelationCallback,
    count?: number
) => Promise<void>;

Create and persist

method make

make: (
    parent: LucidRow,
    callback?: RelationCallback,
    count?: number
) => Promise<void>;

Create and stub

method merge

merge: (attributes: any) => this;

Merge attributes with the relationship and its children

method pivotAttributes

pivotAttributes: (attributes: ModelObject | ModelObject[]) => this;

Define custom pivot attributes for many to many relationship

method useCtx

useCtx: (ctx: FactoryContextContract) => this;

Pass context to the relationship. Must be done everytime, so that relationships uses the same transaction as the parent model

type DefineCallback

type DefineCallback<Model extends LucidModel> = (
    ctx: FactoryContextContract
) =>
    | Promise<Partial<ModelAttributes<InstanceType<Model>>>>
    | Partial<ModelAttributes<InstanceType<Model>>>;

Function to return the model attributes.

type EventsList

type EventsList = 'makeStubbed' | 'create' | 'make';

List of events for which a factory will trigger hooks

type ExtractFactoryAttributes

type ExtractFactoryAttributes<T extends FactoryModelContract<LucidModel>> = Partial<
    ModelAttributes<InstanceType<T['model']>>
>;

Extracts the attributes accepted by the lucid model set on a factory

type HooksHandler

type HooksHandler<Model extends FactoryModelContract<LucidModel>> = (
    builder: FactoryBuilderContract<Model>,
    row: InstanceType<Model['model']>,
    ctx: FactoryContextContract
) => void | Promise<void>;

Shape of hooks handler

type MergeCallback

type MergeCallback<T extends FactoryModelContract<LucidModel>> = (
    row: InstanceType<T['model']>,
    attributes: ExtractFactoryAttributes<T>,
    ctx: FactoryContextContract,
    builder: FactoryBuilderContract<T>
) => void;

Function to merge attributes defined during runtime

type NewUpCallback

type NewUpCallback<T extends FactoryModelContract<LucidModel>> = (
    attributes: ExtractFactoryAttributes<T>,
    ctx: FactoryContextContract,
    model: T['model'],
    builder: FactoryBuilderContract<T>
) => InstanceType<T['model']>;

Function to initiate a model instance. It will receive the attributes returned by the define method

type RelationCallback

type RelationCallback = (
    builder: FactoryBuilderContract<FactoryModelContract<LucidModel>>
) => void;

Callback accepted by the with method and relationships create and make methods

type StateCallback

type StateCallback<Model extends LucidModel> = (
    row: InstanceType<Model>,
    ctx: FactoryContextContract,
    builder: FactoryBuilderContract<FactoryModelContract<Model>>
) => any | Promise<any>;

Callback to define a new model state

type StubIdCallback

type StubIdCallback = (counter: number, model: LucidRow) => any;

Function to generate custom stub ids

namespace @ioc:Adonis/Lucid/Migrator

module '@ioc:Adonis/Lucid/Migrator' {}

variable Migrator

const Migrator: new (
    db: DatabaseContract,
    app: ApplicationContract,
    options: MigratorOptions
) => MigratorContract;

Migrator class constructor

interface MigratorContract

interface MigratorContract extends EventEmitter {}

Shape of the migrator

property direction

direction: 'up' | 'down';

property disableLocks

disableLocks: boolean;

property dryRun

dryRun: boolean;

property error

error: null | Error;

property migratedFiles

migratedFiles: {
    [file: string]: MigratedFileNode;
};

property status

status: 'completed' | 'skipped' | 'pending' | 'error';

property version

version: number;

method close

close: () => Promise<void>;

method getList

getList: () => Promise<MigrationListNode[]>;

method on

on: {
    (event: 'start', callback: () => void): this;
    (event: 'end', callback: () => void): this;
    (event: 'acquire:lock', callback: () => void): this;
    (event: 'release:lock', callback: () => void): this;
    (event: 'create:schema:table', callback: () => void): this;
    (event: 'create:schema_versions:table', callback: () => void): this;
    (
        event: 'upgrade:version',
        callback: (payload: { from: number; to: number }) => void
    ): this;
    (event: 'migration:start', callback: (file: MigratedFileNode) => void): this;
    (
        event: 'migration:completed',
        callback: (file: MigratedFileNode) => void
    ): this;
    (event: 'migration:error', callback: (file: MigratedFileNode) => void): this;
};

method run

run: () => Promise<void>;

type MigratedFileNode

type MigratedFileNode = {
    status: 'completed' | 'error' | 'pending';
    queries: string[];
    file: FileNode<unknown>;
    batch: number;
};

Shape of migrated file within migrator

type MigrationListNode

type MigrationListNode = {
    name: string;
    status: 'pending' | 'migrated' | 'corrupt';
    batch?: number;
    migrationTime?: Date;
};

Shape of migrated file within migrator

type MigratorOptions

type MigratorOptions =
    | {
          direction: 'up';
          connectionName?: string;
          dryRun?: boolean;
          disableLocks?: boolean;
      }
    | {
          direction: 'down';
          batch?: number;
          connectionName?: string;
          dryRun?: boolean;
          disableLocks?: boolean;
      };

Options accepted by migrator constructor

namespace @ioc:Adonis/Lucid/Orm

module '@ioc:Adonis/Lucid/Orm' {}

interface AdapterContract

interface AdapterContract {}

Every adapter must adhere to the Adapter contract

method delete

delete: (instance: LucidRow) => Promise<void>;

Delete model instance

method insert

insert: (instance: LucidRow, attributes: ModelObject) => Promise<void>;

Perform insert

method modelClient

modelClient: (instance: LucidRow) => QueryClientContract;

Returns query client for a model instance by inspecting it's options

method modelConstructorClient

modelConstructorClient: (
    modelConstructor: LucidModel,
    options?: ModelAdapterOptions
) => QueryClientContract;

Returns query client for a model constructor

method query

query: (
    modelConstructor: LucidModel,
    options?: ModelAdapterOptions
) => ModelQueryBuilderContract<LucidModel, LucidRow>;

Must return the query builder for the model

method refresh

refresh: (instance: LucidRow) => Promise<void>;

Refresh model instance to reflect new values from the database

method update

update: (instance: LucidRow, attributes: ModelObject) => Promise<void>;

Perform update

interface LazyLoadAggregatesContract

interface LazyLoadAggregatesContract<Model extends LucidRow> extends Promise<void> {}

Lazy load aggregates for a given model instance

property loadAggregate

loadAggregate: WithAggregate<Model, this>;

property loadCount

loadCount: WithCount<Model, this>;

method exec

exec: () => Promise<void>;

interface LucidModel

interface LucidModel {}

Shape of the model static properties. The $ prefix is to denote special properties from the base model.
@note: Since the interface name appears next to the inherited model methods, we have to choose a succinct name

property $adapter

$adapter: AdapterContract;

Adapter to work as a bridge between query builder and the model

property $columnsDefinitions

$columnsDefinitions: Map<string, ModelColumnOptions>;

A map of defined columns

property $computedDefinitions

$computedDefinitions: Map<string, ComputedOptions>;

A map of computed properties

property $hooks

$hooks: Hooks;

Reference to hooks

property $keys

$keys: {
    attributesToColumns: ModelKeysContract;
    attributesToSerialized: ModelKeysContract;
    columnsToAttributes: ModelKeysContract;
    columnsToSerialized: ModelKeysContract;
    serializedToColumns: ModelKeysContract;
    serializedToAttributes: ModelKeysContract;
};

A copy of internal keys mapping. One should be able to resolve between all key versions

property $relationsDefinitions

$relationsDefinitions: Map<string, RelationshipsContract>;

A map of defined relationships

property booted

readonly booted: boolean;

Whether or not model has been booted. After this model configurations are ignored

property connection

connection?: string;

Custom database connection to use

property namingStrategy

namingStrategy: NamingStrategyContract;

Naming strategy to use

property primaryKey

primaryKey: string;

The primary key for finding unique referencing to a model

property selfAssignPrimaryKey

selfAssignPrimaryKey: boolean;

Self assign the primary instead of relying on the database to return it back

property table

table: string;

Database table to use

method $addColumn

$addColumn: (name: string, options: Partial<ColumnOptions>) => ColumnOptions;

Managing columns

method $addComputed

$addComputed: (
    name: string,
    options: Partial<ComputedOptions>
) => ComputedOptions;

Managing computed columns

method $addRelation

$addRelation: (
    name: string,
    type: ModelRelationTypes['__opaque_type'],
    relatedModel: () => LucidModel,
    options: ModelRelationOptions
) => void;

Managing relationships

method $createFromAdapterResult

$createFromAdapterResult: <T extends LucidModel>(
    this: T,
    result?: ModelObject,
    sideloadAttributes?: ModelObject,
    options?: ModelAdapterOptions
) => null | InstanceType<T>;

Creating model from adapter results

method $createMultipleFromAdapterResult

$createMultipleFromAdapterResult: <T extends LucidModel>(
    this: T,
    results: ModelObject[],
    sideloadAttributes?: ModelObject,
    options?: ModelAdapterOptions
) => InstanceType<T>[];

Creating multiple model instances from an array of adapter result

method $defineProperty

$defineProperty: <Model extends LucidModel, Prop extends keyof Model>(
    this: Model,
    propertyName: Prop,
    defaultValue: Model[Prop],
    strategy: 'inherit' | 'define' | ((value: Model[Prop]) => Model[Prop])
) => void;

Define a static property on the model using the inherit or define strategy.
Inherit strategy will clone the property from the parent model and will set it on the current model

method $getColumn

$getColumn: (name: string) => ModelColumnOptions | undefined;

method $getComputed

$getComputed: (name: string) => ComputedOptions | undefined;

method $getRelation

$getRelation: {
    <
        Model extends LucidModel,
        Name extends ExtractModelRelations<InstanceType<Model>>
    >(
        this: Model,
        name: Name
    ): InstanceType<Model>[Name] extends ModelRelations
        ? InstanceType<Model>[Name]['client']['relation']
        : RelationshipsContract;
    <Model extends LucidModel>(this: Model, name: string): RelationshipsContract;
};

Get relationship declaration

method $hasColumn

$hasColumn: (name: string) => boolean;

method $hasComputed

$hasComputed: (name: string) => boolean;

method $hasRelation

$hasRelation: (name: string) => boolean;

Find if a relationship exists

method after

after: {
    <Model extends LucidModel>(
        this: Model,
        event: 'fetch',
        handler: HooksHandler<InstanceType<Model>[], 'fetch'>
    ): void;
    <Model extends LucidModel>(
        this: Model,
        event: 'paginate',
        handler: HooksHandler<
            ModelPaginatorContract<InstanceType<Model>>,
            'paginate'
        >
    ): void;
    <Model extends LucidModel, Event extends EventsList>(
        this: Model,
        event: Event,
        handler: HooksHandler<InstanceType<Model>, Event>
    ): void;
};

method all

all: <T extends LucidModel>(
    this: T,
    options?: ModelAdapterOptions
) => Promise<InstanceType<T>[]>;

Fetch all rows

method before

before: {
    <Model extends LucidModel, Event extends 'find' | 'fetch'>(
        this: Model,
        event: Event,
        handler: HooksHandler<ModelQueryBuilderContract<Model>, Event>
    ): void;
    <Model extends LucidModel>(
        this: Model,
        event: 'paginate',
        handler: HooksHandler<
            [
                ModelQueryBuilderContract<Model, InstanceType<Model>>,
                ModelQueryBuilderContract<Model, InstanceType<Model>>
            ],
            'paginate'
        >
    ): void;
    <Model extends LucidModel, Event extends EventsList>(
        this: Model,
        event: Event,
        handler: HooksHandler<InstanceType<Model>, Event>
    ): void;
};

method boot

boot: () => void;

Boot model

method create

create: <T extends LucidModel>(
    this: T,
    values: Partial<ModelAttributes<InstanceType<T>>>,
    options?: ModelAssignOptions
) => Promise<InstanceType<T>>;

Create model and return its instance back

method createMany

createMany: <T extends LucidModel>(
    this: T,
    values: Partial<ModelAttributes<InstanceType<T>>>[],
    options?: ModelAssignOptions
) => Promise<InstanceType<T>[]>;

Create many of model instances

method fetchOrCreateMany

fetchOrCreateMany: <T extends LucidModel>(
    this: T,
    predicate:
        | keyof ModelAttributes<InstanceType<T>>
        | (keyof ModelAttributes<InstanceType<T>>)[],
    payload: Partial<ModelAttributes<InstanceType<T>>>[],
    options?: ModelAssignOptions
) => Promise<InstanceType<T>[]>;

Find rows or create many when missing. One db call is invoked for each create

method fetchOrNewUpMany

fetchOrNewUpMany: <T extends LucidModel>(
    this: T,
    predicate:
        | keyof ModelAttributes<InstanceType<T>>
        | (keyof ModelAttributes<InstanceType<T>>)[],
    payload: Partial<ModelAttributes<InstanceType<T>>>[],
    options?: ModelAssignOptions
) => Promise<InstanceType<T>[]>;

Find rows or create in-memory instances of the missing one's.

method find

find: <T extends LucidModel>(
    this: T,
    value: any,
    options?: ModelAdapterOptions
) => Promise<null | InstanceType<T>>;

Find one using the primary key

method findBy

findBy: <T extends LucidModel>(
    this: T,
    key: string,
    value: any,
    options?: ModelAdapterOptions
) => Promise<null | InstanceType<T>>;

Find one using a key-value pair

method findByOrFail

findByOrFail: <T extends LucidModel>(
    this: T,
    key: string,
    value: any,
    options?: ModelAdapterOptions
) => Promise<InstanceType<T>>;

Find one using a key-value pair or fail

method findMany

findMany: <T extends LucidModel>(
    this: T,
    value: any[],
    options?: ModelAdapterOptions
) => Promise<InstanceType<T>[]>;

Find many using an array of primary keys

method findOrFail

findOrFail: <T extends LucidModel>(
    this: T,
    value: any,
    options?: ModelAdapterOptions
) => Promise<InstanceType<T>>;

Find one using the primary key or fail

method first

first: <T extends LucidModel>(
    this: T,
    options?: ModelAdapterOptions
) => Promise<null | InstanceType<T>>;

Same as query().first()

method firstOrCreate

firstOrCreate: <T extends LucidModel>(
    this: T,
    searchPayload: Partial<ModelAttributes<InstanceType<T>>>,
    savePayload?: Partial<ModelAttributes<InstanceType<T>>>,
    options?: ModelAssignOptions
) => Promise<InstanceType<T>>;

Returns the first row or save it to the database

method firstOrFail

firstOrFail: <T extends LucidModel>(
    this: T,
    options?: ModelAdapterOptions
) => Promise<InstanceType<T>>;

Same as query().firstOrFail()

method firstOrNew

firstOrNew: <T extends LucidModel>(
    this: T,
    searchPayload: Partial<ModelAttributes<InstanceType<T>>>,
    savePayload?: Partial<ModelAttributes<InstanceType<T>>>,
    options?: ModelAssignOptions
) => Promise<InstanceType<T>>;

Returns the first row or create a new instance of model without persisting it

method query

query: <Model extends LucidModel, Result = InstanceType<Model>>(
    this: Model,
    options?: ModelAdapterOptions
) => ModelQueryBuilderContract<Model, Result>;

Returns the query for fetching a model instance

method truncate

truncate: (cascade?: boolean) => Promise<void>;

Truncate model table

method updateOrCreate

updateOrCreate: <T extends LucidModel>(
    this: T,
    searchPayload: Partial<ModelAttributes<InstanceType<T>>>,
    updatePayload: Partial<ModelAttributes<InstanceType<T>>>,
    options?: ModelAssignOptions
) => Promise<InstanceType<T>>;

Returns the first row or save it to the database

method updateOrCreateMany

updateOrCreateMany: <T extends LucidModel>(
    this: T,
    predicate:
        | keyof ModelAttributes<InstanceType<T>>
        | (keyof ModelAttributes<InstanceType<T>>)[],
    payload: Partial<ModelAttributes<InstanceType<T>>>[],
    options?: ModelAssignOptions
) => Promise<InstanceType<T>[]>;

Update existing rows or create new one's.

construct signature

new (): LucidRow;

interface LucidRow

interface LucidRow {}

Shape of the model instance. We prefix the properties with a $ to differentiate between special properties provided by the base model but with exception to save, delete, fill, merge and toJSON.
@note: Since the interface name appears next to the inherited model methods, we have to choose a succinct name

property $attributes

$attributes: ModelObject;

property $columns

$columns: undefined;

Columns is a property to get type information for model attributes. This must be declared by the end user

property $dirty

$dirty: ModelObject;

property $extras

$extras: ModelObject;

property $isDeleted

$isDeleted: boolean;

property $isDirty

$isDirty: boolean;

property $isLocal

$isLocal: boolean;

property $isNew

$isNew: boolean;

property $isPersisted

$isPersisted: boolean;

property $options

$options?: ModelOptions;

property $original

$original: ModelObject;

property $preloaded

$preloaded: {
    [relation: string]: LucidRow | LucidRow[];
};

property $primaryKeyValue

$primaryKeyValue?: number | string;

property $sideloaded

$sideloaded: ModelObject;

property $trx

$trx?: TransactionClientContract;

property load

load: LucidRowPreload<this>;

Load relationships onto the instance

property loadAggregate

loadAggregate: <
    Self extends this,
    Name extends ExtractModelRelations<Self>,
    RelatedBuilder = Self[Name] extends ModelRelations
        ? Self[Name]['subQuery']
        : never
>(
    name: Name,
    callback: (builder: RelatedBuilder) => void
) => LazyLoadAggregatesContract<Self>;

Load aggregates

property loadCount

loadCount: <
    Self extends this,
    Name extends ExtractModelRelations<Self>,
    RelatedBuilder = Self[Name] extends ModelRelations
        ? Self[Name]['subQuery']
        : never
>(
    name: Name,
    callback?: (builder: RelatedBuilder) => void
) => LazyLoadAggregatesContract<Self>;

Load count

property preload

preload: LucidRowPreload<this>;

Alias for "load"
Deprecated

method $consumeAdapterResult

$consumeAdapterResult: (
    adapterResult: ModelObject,
    sideloadAttributes?: ModelObject
) => void;

Consume the adapter result and hydrate the model

method $getAttribute

$getAttribute: (key: string) => any;

method $getAttributeFromCache

$getAttributeFromCache: (key: string, callback: CacheNode['getter']) => any;

method $getQueryFor

$getQueryFor: {
    (action: 'insert', client: QueryClientContract): ReturnType<
        QueryClientContract['insertQuery']
    >;
    (
        action: 'update' | 'delete' | 'refresh',
        client: QueryClientContract
    ): ModelQueryBuilderContract<LucidModel, LucidRow>;
};

Gives an option to the end user to define constraints for update, insert and delete queries. Since the query builder for these queries aren't exposed to the end user, this method opens up the API to build custom queries.

method $getRelated

$getRelated: (
    key: string,
    defaultValue?: any
) => OneOrMany<LucidRow> | undefined | null;

method $hasRelated

$hasRelated: (key: string) => boolean;

Read/write realtionships. Following methods are intentionally loosely typed, so that one can bypass the public facing API and type checking for advanced use cases

method $hydrateOriginals

$hydrateOriginals: () => void;

method $pushRelated

$pushRelated: (key: string, result: OneOrMany<LucidRow> | null) => void;

method $setAttribute

$setAttribute: (key: string, value: any) => void;

Read/write attributes. Following methods are intentionally loosely typed, so that one can bypass the public facing API and type checking for advanced use cases

method $setOptionsAndTrx

$setOptionsAndTrx: (options?: ModelAdapterOptions) => void;

method $setRelated

$setRelated: (key: string, result: OneOrMany<LucidRow> | null) => void;

method delete

delete: () => Promise<void>;

method enableForceUpdate

enableForceUpdate: () => this;

Enable force update even when no attributes are dirty

method fill

fill: (
    value: Partial<ModelAttributes<this>>,
    allowExtraProperties?: boolean
) => this;

method merge

merge: (
    value: Partial<ModelAttributes<this>>,
    allowExtraProperties?: boolean
) => this;

method refresh

refresh: () => Promise<this>;

related: <Name extends ExtractModelRelations<this>>(
    relation: Name
) => this[Name] extends ModelRelations ? this[Name]['client'] : never;

Returns related model for a given relationship

method save

save: () => Promise<this>;

Actions to perform on the instance

method serialize

serialize: (cherryPick?: CherryPick) => ModelObject;

Serialize model to a plain object

method serializeAttributes

serializeAttributes: (fields?: CherryPickFields, raw?: boolean) => ModelObject;

Serialize attributes to a plain object

method serializeComputed

serializeComputed: (fields?: CherryPickFields) => ModelObject;

Serialize computed properties to a plain object

method serializeRelations

serializeRelations: {
    (fields: undefined, raw: true): { [key: string]: LucidRow | LucidRow[] };
    (cherryPick: { [relation: string]: CherryPick }, raw: false): ModelObject;
    (
        cherryPick?: { [relation: string]: CherryPick },
        raw?: boolean
    ): ModelObject;
};

Serialize relationships to key-value pair of model instances and their serializeAs keys
Serialize relationships to key-value pair of plain nested objects

method toJSON

toJSON: () => ModelObject;

Serialize everything

method toObject

toObject: () => ModelObject;

Converts model to an object. It just returns the properties of the model, along with preloaded relationships

method useConnection

useConnection: (connection: string) => this;

method useTransaction

useTransaction: (trx: TransactionClientContract) => this;

interface LucidRowAggregate

interface LucidRowAggregate<Model extends LucidRow>
    extends Preload<Model, Promise<void>> {}

call signature

(callback: (preloader: PreloaderContract<Model>) => void): Promise<void>;

interface LucidRowPreload

interface LucidRowPreload<Model extends LucidRow>
    extends Preload<Model, Promise<void>> {}

Preload function on a model instance

call signature

(callback: (preloader: PreloaderContract<Model>) => void): Promise<void>;

interface ModelKeysContract

interface ModelKeysContract {}

Shape of model keys

method add

add: (key: string, value: string) => void;

method all

all: () => ModelObject;

method get

get: {
    (key: string, defaultValue: string): string;
    (key: string, defaultValue?: string): string;
};

method resolve

resolve: (key: string) => string;

interface ModelObject

interface ModelObject {}

Reusable interface to define an object.

index signature

[key: string]: any;

interface ModelPaginatorContract

interface ModelPaginatorContract<Result extends LucidRow>
    extends Omit<SimplePaginatorContract<Result>, 'toJSON'> {}

An extension of the simple paginator with support for serializing models

method serialize

serialize: (cherryPick?: CherryPick) => { meta: any; data: ModelObject[] };

method toJSON

toJSON: () => { meta: any; data: ModelObject[] };

interface ModelQueryBuilderContract

interface ModelQueryBuilderContract<
    Model extends LucidModel,
    Result = InstanceType<Model>
> extends ChainableContract,
        ExcutableQueryBuilderContract<Result[]> {}

Model query builder will have extras methods on top of the Database query builder

property andDoesntHave

andDoesntHave: Has<InstanceType<Model>, this>;

property andHas

andHas: Has<InstanceType<Model>, this>;

property andWhereDoesntHave

andWhereDoesntHave: WhereHas<InstanceType<Model>, this>;

property andWhereHas

andWhereHas: WhereHas<InstanceType<Model>, this>;

property avg

avg: Aggregate<this>;

property avgDistinct

avgDistinct: Aggregate<this>;

property client

client: QueryClientContract;

Reference to query client used for making queries

property clientOptions

readonly clientOptions: ModelAdapterOptions;

A copy of client options.

property count

count: Aggregate<this>;

Aggregates

property countDistinct

countDistinct: Aggregate<this>;

property decrement

decrement: Counter<ModelQueryBuilderContract<Model, any>>;

property doesntHave

doesntHave: Has<InstanceType<Model>, this>;

property has

has: Has<InstanceType<Model>, this>;

Add where constraint using the relationship

property increment

increment: Counter<ModelQueryBuilderContract<Model, any>>;

property isChildQuery

isChildQuery: boolean;

Whether or not the query is a child query generated for .where callbacks

property max

max: Aggregate<this>;

property min

min: Aggregate<this>;

property model

model: Model;

property orDoesntHave

orDoesntHave: Has<InstanceType<Model>, this>;

property orHas

orHas: Has<InstanceType<Model>, this>;

property orWhereDoesntHave

orWhereDoesntHave: WhereHas<InstanceType<Model>, this>;

property orWhereHas

orWhereHas: WhereHas<InstanceType<Model>, this>;

property preload

preload: Preload<InstanceType<Model>, this>;

Define relationships to be preloaded

property returning

returning: Returning<this>;

property sum

sum: Aggregate<this>;