querier-ts 0.0.0

package/lib/query.d.ts

@@ -0,0 +1,215 @@
+import { addPrefixToObject, PropertyOnly, PropOf } from './utils/types';
+import { QueryConditionsGroup } from './query-conditions-group';
+import { QueryConditionsGroupNullable } from './query-conditions-group-nullable';
+/**
+ * Allows filtering data from an array of objects.
+ *
+ * @example
+ * ```ts
+ * interface User {
+ *   id: string;
+ *   email: string;
+ *   isActive: boolean;
+ *   createdAt: string;
+ *   updatedAt: string;
+ * }
+ *
+ * const users: User[] = [];
+ *
+ * // Filtering objects
+ *
+ * const activeGmailUsers = Query.from(users)
+ *   .where({
+ *     isActive: true,
+ *     email: (email) => email.endsWith('@gmail.com'),
+ *   })
+ *   .all();
+ *
+ * // Selecting specific data
+ *
+ * const userEmails = Query.from(users)
+ *   .select('email')
+ *   .column();
+ *
+ * const lastUserId = Query.from(users)
+ *   .select('id')
+ *   .orderBy('-createdAt')
+ *   .scalar();
+ *
+ * // Checking information
+ *
+ * const userExists = Query.from(users)
+ *   .where({
+ *     id: 'some-id',
+ *   })
+ *   .exists();
+ *
+ * const numberOfUsers = Query.from(users).count();
+ * ```
+ */
+export declare class Query<T extends object> {
+    #private;
+    /**
+     * Indicates whether conditions with `null` and `undefined` values should be
+     * skipped.
+     */
+    private ignoreNullValues;
+    /**
+     * Initializes the query.
+     *
+     * @param {T[]} rows Rows to be queried.
+     */
+    private constructor();
+    /**
+     * Creates a new query based on the given data.
+     *
+     * @param {T[]} rows Rows to be queried.
+     *
+     * @returns {Query<T>} Query to the given rows.
+     */
+    static from<T extends object>(rows: T[]): Query<T>;
+    /**
+     * Defines specific columns to be returned on the final results.
+     *
+     * @param {PropOf<T> | PropOf<T>[]} columns Selected columns.
+     *
+     * @returns {this} Current query.
+     */
+    select(columns: PropOf<T> | PropOf<T>[]): this;
+    /**
+     * Applies conditions to the query.
+     *
+     * @param {QueryConditionsGroup<T> | ((obj: T) => boolean)} condition Filter to
+     * be applied to the query.
+     *
+     * If a callback function is provided, it must return a boolean value.
+     *
+     * If an object is provided, its properties must be attributes of `T` and their
+     * corresponding values must be the expected values for the attributes or a
+     * callback functions that return boolean values.
+     *
+     * @returns {this} Current query.
+     */
+    where(condition: QueryConditionsGroup<T> | ((obj: T) => boolean)): this;
+    /**
+     * Applies a set of conditions to the query ignoring `null` and `undefined`
+     * values as conditions.
+     *
+     * @param {QueryConditionsGroupNullable<T>} condition An object where each
+     * property represents an attribute to be validated. The values can be
+     * literal or callback functions that return a boolean. If `null` or `undefined`
+     * is passed, that condition will be skipped.
+     *
+     * @returns {this} Current query.
+     */
+    filterWhere(condition: QueryConditionsGroupNullable<T>): this;
+    /**
+     * Adds ordering to the results.
+     *
+     * @param {(PropOf<T> | keyof addPrefixToObject<PropertyOnly<T>, '-'>)[]} columns
+     * Ascending or descending columns. To mark a field as descending, use `-` before
+     * its name.
+     *
+     * @returns {this} Current query.
+     */
+    orderBy(...columns: (PropOf<T> | keyof addPrefixToObject<PropertyOnly<T>, '-'>)[]): this;
+    /**
+     * Returns the current number of rows.
+     *
+     * @return {number}
+     */
+    count(): number;
+    /**
+     * Checks if there is at least one row compatible with the query.
+     *
+     * @returns {boolean} Boolean indicating whether any row exists.
+     */
+    exists(): boolean;
+    /**
+     * Returns the first result.
+     *
+     * @returns {T}
+     */
+    first(): T | null;
+    /**
+     * Returns the last result.
+     *
+     * @returns {T}
+     */
+    last(): T | null;
+    /**
+     * Returns all results.
+     *
+     * @returns {T[]}
+     */
+    all(): T[];
+    /**
+     * Returns the value of the first (selected) column of the first row.
+     *
+     * @returns {T[Promise<T>]|false} First value or `false`, if none row exists.
+     */
+    scalar(): T[PropOf<T>] | false;
+    /**
+     * Returns the values of the first (selected) column of all rows.
+     *
+     * @returns {T[Promise<T>][]} Values from the first (selected) column.
+     */
+    column(): T[PropOf<T>][];
+    /**
+     * Returns the values of the rows. If there are selected columns, only their
+     * values will be returned.
+     *
+     * @returns {T[PropOf<T>][][]} Array with the values of all rows.
+     */
+    values(): T[PropOf<T>][][];
+    /**
+     * Defines the number of rows to skip.
+     *
+     * @param {number} numberOfRows Numbers of rows to skip. Only non negative integer numbers
+     * are allowed.
+     *
+     * @returns {this} Current query.
+     *
+     * @throws {InvalidArgumentError} If the given number is less than 0.
+     */
+    skip(numberOfRows: number): this;
+    /**
+     * Defines a limit for the number of results.
+     *
+     * @param {number} limit Limit of results. Only non negative integer numbers are allowed.
+     *
+     * @returns {this} Current query.
+     *
+     * @throws {InvalidArgumentError} If the given limit is less than 0.
+     */
+    limit(limit: number): this;
+    /**
+     * Returns the rows that should be used in the final results.
+     *
+     * @returns {T[]} Rows within the specified limit.
+     */
+    private getLimitedRows;
+    /**
+     * Returns the first selected column or the first key of some row.
+     *
+     * @returns {Promise<T>|null} The first column or `null`, if none is selected
+     * or there is no row.
+     */
+    private getFirstColumn;
+    /**
+     * Filters the rows according to the given conditions.
+     *
+     * @param {QueryConditionsGroupNullable<T> | ((obj: T) => boolean)} condition
+     * Object or callback function.
+     */
+    private filterRows;
+    /**
+     * Validates a row based on the given conditions object.
+     *
+     * @param {T} row Row to validate.
+     * @param {QueryConditionsGroupNullable<T>} condition Conditions object.
+     *
+     * @returns {boolean} Validation result.
+     */
+    private validateRow;
+}

package/lib/query.js

@@ -0,0 +1,331 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Query_rows, _Query_columns, _Query_startAt, _Query_limit;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Query = void 0;
+const sort_1 = require("./utils/functions/sort");
+const type_guards_1 = require("./utils/functions/type-guards");
+const query_row_validator_1 = require("./query-row-validator");
+const number_validaton_1 = require("./utils/decorators/number-validaton");
+/**
+ * Allows filtering data from an array of objects.
+ *
+ * @example
+ * ```ts
+ * interface User {
+ *   id: string;
+ *   email: string;
+ *   isActive: boolean;
+ *   createdAt: string;
+ *   updatedAt: string;
+ * }
+ *
+ * const users: User[] = [];
+ *
+ * // Filtering objects
+ *
+ * const activeGmailUsers = Query.from(users)
+ *   .where({
+ *     isActive: true,
+ *     email: (email) => email.endsWith('@gmail.com'),
+ *   })
+ *   .all();
+ *
+ * // Selecting specific data
+ *
+ * const userEmails = Query.from(users)
+ *   .select('email')
+ *   .column();
+ *
+ * const lastUserId = Query.from(users)
+ *   .select('id')
+ *   .orderBy('-createdAt')
+ *   .scalar();
+ *
+ * // Checking information
+ *
+ * const userExists = Query.from(users)
+ *   .where({
+ *     id: 'some-id',
+ *   })
+ *   .exists();
+ *
+ * const numberOfUsers = Query.from(users).count();
+ * ```
+ */
+class Query {
+    /**
+     * Initializes the query.
+     *
+     * @param {T[]} rows Rows to be queried.
+     */
+    constructor(rows) {
+        /**
+         * Rows to be queried.
+         */
+        _Query_rows.set(this, []);
+        /**
+         * Selected columns.
+         */
+        _Query_columns.set(this, []);
+        /**
+         * Number of results to skip.
+         */
+        _Query_startAt.set(this, 0);
+        /**
+         * Limit of results.
+         */
+        _Query_limit.set(this, void 0);
+        /**
+         * Indicates whether conditions with `null` and `undefined` values should be
+         * skipped.
+         */
+        this.ignoreNullValues = false;
+        __classPrivateFieldSet(this, _Query_rows, [...rows], "f");
+    }
+    /**
+     * Creates a new query based on the given data.
+     *
+     * @param {T[]} rows Rows to be queried.
+     *
+     * @returns {Query<T>} Query to the given rows.
+     */
+    static from(rows) {
+        return new Query(rows);
+    }
+    /**
+     * Defines specific columns to be returned on the final results.
+     *
+     * @param {PropOf<T> | PropOf<T>[]} columns Selected columns.
+     *
+     * @returns {this} Current query.
+     */
+    select(columns) {
+        __classPrivateFieldSet(this, _Query_columns, Array.isArray(columns) ? columns : [columns], "f");
+        return this;
+    }
+    /**
+     * Applies conditions to the query.
+     *
+     * @param {QueryConditionsGroup<T> | ((obj: T) => boolean)} condition Filter to
+     * be applied to the query.
+     *
+     * If a callback function is provided, it must return a boolean value.
+     *
+     * If an object is provided, its properties must be attributes of `T` and their
+     * corresponding values must be the expected values for the attributes or a
+     * callback functions that return boolean values.
+     *
+     * @returns {this} Current query.
+     */
+    where(condition) {
+        this.filterRows(condition);
+        return this;
+    }
+    /**
+     * Applies a set of conditions to the query ignoring `null` and `undefined`
+     * values as conditions.
+     *
+     * @param {QueryConditionsGroupNullable<T>} condition An object where each
+     * property represents an attribute to be validated. The values can be
+     * literal or callback functions that return a boolean. If `null` or `undefined`
+     * is passed, that condition will be skipped.
+     *
+     * @returns {this} Current query.
+     */
+    filterWhere(condition) {
+        this.ignoreNullValues = true;
+        this.filterRows(condition);
+        this.ignoreNullValues = false;
+        return this;
+    }
+    /**
+     * Adds ordering to the results.
+     *
+     * @param {(PropOf<T> | keyof addPrefixToObject<PropertyOnly<T>, '-'>)[]} columns
+     * Ascending or descending columns. To mark a field as descending, use `-` before
+     * its name.
+     *
+     * @returns {this} Current query.
+     */
+    orderBy(...columns) {
+        __classPrivateFieldGet(this, _Query_rows, "f").sort((0, sort_1.sortByProperties)(...columns));
+        return this;
+    }
+    /**
+     * Returns the current number of rows.
+     *
+     * @return {number}
+     */
+    count() {
+        return this.getLimitedRows().length;
+    }
+    /**
+     * Checks if there is at least one row compatible with the query.
+     *
+     * @returns {boolean} Boolean indicating whether any row exists.
+     */
+    exists() {
+        return this.count() > 0;
+    }
+    /**
+     * Returns the first result.
+     *
+     * @returns {T}
+     */
+    first() {
+        const rows = this.getLimitedRows();
+        return rows.length ? rows[0] : null;
+    }
+    /**
+     * Returns the last result.
+     *
+     * @returns {T}
+     */
+    last() {
+        const rows = this.getLimitedRows();
+        return rows[this.count() - 1] ?? null;
+    }
+    /**
+     * Returns all results.
+     *
+     * @returns {T[]}
+     */
+    all() {
+        return this.getLimitedRows();
+    }
+    /**
+     * Returns the value of the first (selected) column of the first row.
+     *
+     * @returns {T[Promise<T>]|false} First value or `false`, if none row exists.
+     */
+    scalar() {
+        const firstObject = this.first();
+        const firstColumn = this.getFirstColumn();
+        return firstObject && firstColumn ? firstObject[firstColumn] ?? false : false;
+    }
+    /**
+     * Returns the values of the first (selected) column of all rows.
+     *
+     * @returns {T[Promise<T>][]} Values from the first (selected) column.
+     */
+    column() {
+        const firstColumn = this.getFirstColumn();
+        if (!firstColumn) {
+            return [];
+        }
+        return this.getLimitedRows().map((row) => row[firstColumn]);
+    }
+    /**
+     * Returns the values of the rows. If there are selected columns, only their
+     * values will be returned.
+     *
+     * @returns {T[PropOf<T>][][]} Array with the values of all rows.
+     */
+    values() {
+        return this.getLimitedRows().map((row) => __classPrivateFieldGet(this, _Query_columns, "f").length ? __classPrivateFieldGet(this, _Query_columns, "f").map((column) => row[column]) : Object.values(row));
+    }
+    /**
+     * Defines the number of rows to skip.
+     *
+     * @param {number} numberOfRows Numbers of rows to skip. Only non negative integer numbers
+     * are allowed.
+     *
+     * @returns {this} Current query.
+     *
+     * @throws {InvalidArgumentError} If the given number is less than 0.
+     */
+    skip(numberOfRows) {
+        __classPrivateFieldSet(this, _Query_startAt, numberOfRows, "f");
+        return this;
+    }
+    /**
+     * Defines a limit for the number of results.
+     *
+     * @param {number} limit Limit of results. Only non negative integer numbers are allowed.
+     *
+     * @returns {this} Current query.
+     *
+     * @throws {InvalidArgumentError} If the given limit is less than 0.
+     */
+    limit(limit) {
+        __classPrivateFieldSet(this, _Query_limit, limit, "f");
+        return this;
+    }
+    /**
+     * Returns the rows that should be used in the final results.
+     *
+     * @returns {T[]} Rows within the specified limit.
+     */
+    getLimitedRows() {
+        return __classPrivateFieldGet(this, _Query_rows, "f").slice(__classPrivateFieldGet(this, _Query_startAt, "f")).slice(0, __classPrivateFieldGet(this, _Query_limit, "f"));
+    }
+    /**
+     * Returns the first selected column or the first key of some row.
+     *
+     * @returns {Promise<T>|null} The first column or `null`, if none is selected
+     * or there is no row.
+     */
+    getFirstColumn() {
+        if (__classPrivateFieldGet(this, _Query_columns, "f").length) {
+            return __classPrivateFieldGet(this, _Query_columns, "f")[0];
+        }
+        const firstObject = this.first();
+        return firstObject ? Object.keys(firstObject)[0] : null;
+    }
+    /**
+     * Filters the rows according to the given conditions.
+     *
+     * @param {QueryConditionsGroupNullable<T> | ((obj: T) => boolean)} condition
+     * Object or callback function.
+     */
+    filterRows(condition) {
+        const isCallbackValidator = (0, type_guards_1.isFunction)(condition);
+        __classPrivateFieldSet(this, _Query_rows, __classPrivateFieldGet(this, _Query_rows, "f").filter((row) => (isCallbackValidator ? condition(row) : this.validateRow(row, condition))), "f");
+    }
+    /**
+     * Validates a row based on the given conditions object.
+     *
+     * @param {T} row Row to validate.
+     * @param {QueryConditionsGroupNullable<T>} condition Conditions object.
+     *
+     * @returns {boolean} Validation result.
+     */
+    validateRow(row, condition) {
+        return query_row_validator_1.QueryRowValidator.validate(row, {
+            conditionsObject: condition,
+            ignoreNullValues: this.ignoreNullValues,
+        });
+    }
+}
+_Query_rows = new WeakMap(), _Query_columns = new WeakMap(), _Query_startAt = new WeakMap(), _Query_limit = new WeakMap();
+__decorate([
+    number_validaton_1.validateNumbers,
+    __param(0, number_validaton_1.integer),
+    __param(0, (0, number_validaton_1.min)(0))
+], Query.prototype, "skip", null);
+__decorate([
+    number_validaton_1.validateNumbers,
+    __param(0, number_validaton_1.integer),
+    __param(0, (0, number_validaton_1.min)(0))
+], Query.prototype, "limit", null);
+exports.Query = Query;

package/lib/utils/decorators/number-validaton.d.ts

@@ -0,0 +1,36 @@
+import 'reflect-metadata';
+/**
+ * Sets a minimal value to be used as argument to the given parameter.
+ *
+ * @param {number} value Minimal value to set.
+ *
+ * @returns Decorator function.
+ */
+export declare function min(value: number): (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Sets a maximum value to be used as argument to the given parameter.
+ *
+ * @param {number} value Maximal value to set.
+ *
+ * @returns Decorator function.
+ */
+export declare function max(value: number): (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Marks the given parameter as an integer.
+ *
+ * @param {Object} target Class to which the parameter belongs.
+ * @param {string} propertyKey Method name.
+ * @param {number} parameterIndex Parameter index.
+ */
+export declare function integer(target: object, propertyKey: string | symbol, parameterIndex: number): void;
+/**
+ * Validates the property decorators `integer`, `min`, and `max`, throwing and error
+ * when the arguments passed to the parameters decorated by them are invalid.
+ *
+ * @param {any} target Class to which the method belongs.
+ * @param {string} propertyName Method name.
+ * @param {TypedPropertyDescriptor<any>} descriptor Descriptor object.
+ *
+ * @throws {InvalidArgumentError} If an argument is invalid.
+ */
+export declare function validateNumbers(target: any, propertyName: string, descriptor: TypedPropertyDescriptor<any>): void;

package/lib/utils/decorators/number-validaton.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateNumbers = exports.integer = exports.max = exports.min = void 0;
+require("reflect-metadata");
+const errors_1 = require("../../errors");
+const type_guards_1 = require("../functions/type-guards");
+const minMetadataKey = Symbol('min');
+const maxMetadataKey = Symbol('max');
+const integerMetadataKey = Symbol('integer');
+/**
+ * Sets a minimal value to be used as argument to the given parameter.
+ *
+ * @param {number} value Minimal value to set.
+ *
+ * @returns Decorator function.
+ */
+function min(value) {
+    return (target, propertyKey, parameterIndex) => {
+        const minParameters = Reflect.getOwnMetadata(minMetadataKey, target, propertyKey) || [];
+        minParameters.push({
+            value,
+            index: parameterIndex,
+        });
+        Reflect.defineMetadata(minMetadataKey, minParameters, target, propertyKey);
+    };
+}
+exports.min = min;
+/**
+ * Sets a maximum value to be used as argument to the given parameter.
+ *
+ * @param {number} value Maximal value to set.
+ *
+ * @returns Decorator function.
+ */
+function max(value) {
+    return (target, propertyKey, parameterIndex) => {
+        const maxParameters = Reflect.getOwnMetadata(maxMetadataKey, target, propertyKey) || [];
+        maxParameters.push({
+            value,
+            index: parameterIndex,
+        });
+        Reflect.defineMetadata(maxMetadataKey, maxParameters, target, propertyKey);
+    };
+}
+exports.max = max;
+/**
+ * Marks the given parameter as an integer.
+ *
+ * @param {Object} target Class to which the parameter belongs.
+ * @param {string} propertyKey Method name.
+ * @param {number} parameterIndex Parameter index.
+ */
+function integer(target, propertyKey, parameterIndex) {
+    const integerParameters = Reflect.getOwnMetadata(integerMetadataKey, target, propertyKey) || [];
+    integerParameters.push({
+        index: parameterIndex,
+    });
+    Reflect.defineMetadata(integerMetadataKey, integerParameters, target, propertyKey);
+}
+exports.integer = integer;
+/**
+ * Validates the property decorators `integer`, `min`, and `max`, throwing and error
+ * when the arguments passed to the parameters decorated by them are invalid.
+ *
+ * @param {any} target Class to which the method belongs.
+ * @param {string} propertyName Method name.
+ * @param {TypedPropertyDescriptor<any>} descriptor Descriptor object.
+ *
+ * @throws {InvalidArgumentError} If an argument is invalid.
+ */
+function validateNumbers(target, propertyName, descriptor) {
+    const method = descriptor.value;
+    descriptor.value = function () {
+        const minParams = Reflect.getOwnMetadata(minMetadataKey, target, propertyName) || [];
+        const maxParams = Reflect.getOwnMetadata(maxMetadataKey, target, propertyName) || [];
+        const integerParams = Reflect.getOwnMetadata(integerMetadataKey, target, propertyName) || [];
+        checkMinParams(propertyName, minParams, arguments);
+        checkMaxParams(propertyName, maxParams, arguments);
+        checkIntegerParams(propertyName, integerParams, arguments);
+        return method.apply(this, arguments);
+    };
+}
+exports.validateNumbers = validateNumbers;
+function checkMinParams(methodName, params, actualArguments) {
+    for (const parameter of params) {
+        const actualValue = actualArguments[parameter.index];
+        const minValue = parameter.value;
+        if (!(0, type_guards_1.isNumber)(actualValue) || actualValue < minValue) {
+            throw new errors_1.InvalidArgumentError({
+                method: methodName,
+                param: parameter.index,
+                argument: actualValue,
+                expected: `equal or greater than ${minValue}`,
+            });
+        }
+    }
+}
+function checkMaxParams(methodName, params, actualArguments) {
+    for (const parameter of params) {
+        const actualValue = actualArguments[parameter.index];
+        const maxValue = parameter.value;
+        if (!(0, type_guards_1.isNumber)(actualValue) || actualValue > maxValue) {
+            throw new errors_1.InvalidArgumentError({
+                method: methodName,
+                param: parameter.index,
+                argument: actualValue,
+                expected: `equal or less than ${maxValue}`,
+            });
+        }
+    }
+}
+function checkIntegerParams(methodName, params, actualArguments) {
+    for (const { index } of params) {
+        const actualValue = actualArguments[index];
+        if (!Number.isSafeInteger(actualValue)) {
+            throw new errors_1.InvalidArgumentError({
+                method: methodName,
+                param: index,
+                argument: actualValue,
+                expected: 'an integer',
+            });
+        }
+    }
+}