trilogy/dist/model.d.ts

TypeScript SQLite layer with support for both native C++ & pure JavaScript drivers.

import { Trilogy } from '.';
import { Hooks } from './hooks';
import { Cast } from './schema-helpers';
import * as types from './types';
/**
 * Instances of `Model` manage the casting of values back and forth between the
 * SQLite backend and their corresponding JavaScript types as well as calling
 * hooks.
 *
 * Models are created using a trilogy instance's `model` method and are not
 * intended to be created directly.
 *
 * @internal
 */
export default class Model<D extends types.ReturnDict = types.LooseObject> extends Hooks<D> {
    ctx: Trilogy;
    name: string;
    options: types.ModelOptions;
    cast: Cast<D>;
    schema: types.Schema<D>;
    /**
     * @param ctx trilogy instance used as a context for the model
     * @param name Name associated with this model and used in the backend
     * @param schema An object defining the fields & types of objects
     * @param options
     */
    constructor(ctx: Trilogy, name: string, schema: types.SchemaRaw<D>, options: types.ModelOptions);
    /**
     * Create an object on the given model. `object` should match the model's
     * defined schema but values will cast into types as needed.
     *
     * @param object Data to insert
     * @param options
     */
    create(object: D, options?: types.CreateOptions): Promise<D | undefined>;
    /**
     * Find all objects matching a given criteria.
     *
     * @param criteria Criteria used to restrict selection
     * @param options
     */
    find(criteria?: types.Criteria<D>, options?: types.FindOptions): Promise<D[]>;
    /**
     * Find all objects matching a given criteria and extract the values
     * at `column`.
     *
     * @param column Property name of objects to extract the value from
     * @param criteria Criteria used to restrict selection
     * @param options
     */
    findIn(column: keyof D, criteria?: types.Criteria<D>, options?: types.FindOptions): Promise<types.ValueOf<D>[]>;
    /**
     * Find a single object matching a given criteria. The first matching
     * object is returned.
     *
     * @param criteria Criteria used to restrict selection
     * @param options
     */
    findOne(criteria?: types.Criteria<D>, options?: types.FindOptions): Promise<D | undefined>;
    /**
     * Find a single object matching a given criteria and extract the value
     * at `column`. The first matching object is returned.
     *
     * @param column Property name of the selected object to extract the value from
     * @param criteria Criteria used to restrict selection
     * @param options
     */
    findOneIn<K extends keyof D = keyof D, V = D[K]>(column: K, criteria?: types.Criteria<D>, options?: types.FindOptions): Promise<V | undefined>;
    /**
     * Find a matching object based on the given criteria, or create it if it
     * doesn't exist. When creating the object, a merged object created from
     * `criteria` and `creation` will be used, with the properties from
     * `creation` taking precedence.
     *
     * @param criteria Criteria to search for
     * @param creation Data used to create the object if it doesn't exist
     * @param options
     */
    findOrCreate(criteria: types.CriteriaObj<D>, creation?: Partial<D>, options?: types.FindOptions): Promise<D | undefined>;
    /**
     * Modify the properties of an existing object. While optional, if `data`
     * contains no properties no update queries will be run.
     *
     * @param criteria Criteria used to restrict selection
     * @param data Updates to be made on matching objects
     * @param options
     */
    update(criteria?: types.Criteria<D>, data?: Partial<D>, options?: types.UpdateOptions): Promise<D[]>;
    /**
     * Update an existing object or create it if it doesn't exist. If creation
     * is necessary a merged object created from `criteria` and `data` will be
     * used, with the properties from `data` taking precedence.
     *
     * @param criteria Criteria used to restrict selection
     * @param data Updates to be made on matching objects
     * @param options
     */
    updateOrCreate(criteria: types.CriteriaObj<D>, data: Partial<D>, options?: types.UpdateOptions & types.CreateOptions): Promise<D[]>;
    /**
     * Works similarly to the `get` methods in lodash, underscore, etc. Returns
     * the value at `column` or, if it does not exist, the supplied `defaultValue`.
     * Essentially a useful shorthand for some `find` scenarios.
     *
     * @param column Property name of the object to extract the value from
     * @param criteria Criteria used to restrict selection
     * @param defaultValue Value returned if the result doesn't exist
     */
    get<K extends keyof D = keyof D, V extends D[K] = D[K]>(column: K, criteria?: types.Criteria<D>, defaultValue?: V): Promise<D[K] | undefined>;
    /**
     * Works similarly to the `set` methods in lodash, underscore, etc. Updates
     * the value at `column` to be `value` where the given criteria is met.
     *
     * @param column Property name of the object at which to set the value
     * @param criteria Criteria used to restrict selection
     * @param value Value returned if the result doesn't exist
     */
    set<K extends keyof D = keyof D, V extends D[K] = D[K]>(column: K, criteria: types.Criteria<D>, value: V): Promise<D[]>;
    /**
     * Works exactly like `get` but bypasses getters and retrieves the raw database value.
     *
     * @param column Property name of the object to extract the value from
     * @param criteria Criteria used to restrict selection
     * @param defaultValue Value returned if the result doesn't exist
     */
    getRaw<K extends keyof D = keyof D, V extends D[K] = D[K]>(column: K, criteria: types.Criteria<D>, defaultValue?: V): Promise<D[K] | undefined>;
    /**
     * Works exactly like `set` but bypasses setters when updating the target value.
     *
     * @param column Property name of the object at which to set the value
     * @param criteria Criteria used to restrict selection
     * @param value Value returned if the result doesn't exist
     */
    setRaw<K extends keyof D = keyof D, V extends D[K] = D[K]>(column: K, criteria: types.Criteria<D>, value: V): Promise<D[]>;
    /**
     * Increment the value of a given model's property by the specified amount,
     * which defaults to `1` if not provided.
     *
     * @param column Property at which to increment the value
     * @param criteria Criteria used to restrict selection
     * @param amount
     */
    increment(column: keyof D, criteria?: types.Criteria<D>, amount?: number): Promise<D[]>;
    /**
     * Decrement the value of a given model's property by the specified amount,
     * which defaults to `1` if not provided.
     *
     * @param column Property at which to decrement the value
     * @param criteria Criteria used to restrict selection
     * @param amount
     */
    decrement(column: keyof D, criteria?: types.Criteria<D>, amount?: number, allowNegative?: boolean): Promise<D[]>;
    /**
     * Delete objects from this model that match `criteria`.
     *
     * @remarks
     * If `criteria` is empty or absent, nothing will be done. This is a safeguard
     * against unintentionally deleting everything in the model. Use `clear` if
     * you really want to remove all rows.
     *
     * @param criteria Criteria used to restrict selection
     */
    remove(criteria: types.Criteria<D>): Promise<D[]>;
    /**
     * Delete all objects from this model.
     */
    clear(): Promise<number>;
    /**
     * Count the number of objects in this model.
     *
     * @param criteria Criteria used to restrict selection
     * @param options
     */
    count(criteria?: types.Criteria<D>, options?: types.AggregateOptions): Promise<number>;
    /**
     * Count the number of objects in this model, selecting on column (meaning
     * `NULL` values are not counted).
     *
     * @param column Property name to select on
     * @param criteria Criteria used to restrict selection
     * @param options
     */
    countIn(column: keyof D, criteria?: types.Criteria<D>, options?: types.AggregateOptions): Promise<number>;
    /**
     * Find the minimum value contained in this model, comparing all values in
     * `column` that match the given criteria.
     *
     * @param column Property name to inspect
     * @param criteria Criteria used to restrict selection
     * @param options
     */
    min(column: keyof D, criteria?: types.Criteria<D>, options?: types.AggregateOptions): Promise<number | undefined>;
    /**
     * Find the maximum value contained in this model, comparing all values in
     * `column` that match the given criteria.
     *
     * @param column Property name to inspect
     * @param criteria Criteria used to restrict selection
     * @param options
     */
    max(column: keyof D, criteria?: types.Criteria<D>, options?: types.AggregateOptions): Promise<number | undefined>;
}