querier-ts 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Luiz Filipe da Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+# query-ts
+
+A package that allows you to query data from an array of objects.
+
+## Introduction
+
+The following data will be used in the samples of this documentation:
+
+```ts
+interface UserPermissions {
+  useCookies: boolean;
+  sendNotifications: boolean;
+}
+
+class User {
+  id: number;
+  name: string;
+  permissions: UserPermissions;
+  isActive: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+
+  isAdmin(): boolean {
+    ...
+  }
+}
+
+const users: User[] = [
+  ...
+];
+```
+
+## `Query`
+
+A `Query` can be created this way:
+
+```ts
+const usersQuery = Query.from(users);
+```
+
+TypeScript will automatically assume that the query data type is `User`. You can make it explicit:
+
+```ts
+const usersQuery = Query.from<User>(users);
+```
+
+### Getting results
+
+#### `all()`
+
+Returns all results.
+
+#### `first()`
+
+Returns the first result.
+
+#### `last()`
+
+Returns the last result.
+
+#### `count()`
+
+Returns the number of results.
+
+#### `exists()`
+
+Returns a boolean indicating whether any results exist.
+
+### Filtering data
+
+#### `where(condition)`
+
+There are two types of parameters:
+
+1. An object where each property represents an attribute to be validated.
+2. A callback function that returns a boolean validating the object.
+
+When the condition is an object, you can pass literal values or callback functions to each attribute that needs to be validated.
+
+```ts
+const activeGmailUsers = Query.from(users)
+  .where({
+    isActive: true,
+    email: (email) => email.endsWith('@gmail.com'),
+  })
+  .where((user) => (
+    !user.isAdmin()
+  ))
+  .all();
+```
+
+It also works on inner objects:
+
+```ts
+  .where({
+    permissions: {
+      sendNotifications: true,
+    },
+  })
+```
+
+#### `filterWhere(condition)`
+
+The difference of `filterWhere` is that it only accepts an object and it ignores conditions whose values are `null` or `undefined`.
+
+```ts
+let isActive: bool;
+
+const filteredUsers = Query.from(users)
+  .filterWhere({
+    id: 1,
+    isActive: isActive, // this condition will be skipped
+  })
+  .all();
+```
+
+>**Remember**: if you want to check if a value is really `null` or `undefined`, use `where()`.
+
+### Selecting specific data
+
+#### `select(columns)`
+
+This method can be combined with `scalar()`, `column()`, or `values()`. It determines which columns should be selected.
+
+It accepts a string containing a single column name or an array of column names.
+
+```ts
+  .select('id')
+```
+
+#### `scalar()`
+
+It returns the value of the first property of the first object.
+
+```ts
+const firstId = Query.from(users).scalar();
+```
+
+As mentioned above, it is possible to combine it with `select()` in order to get the value of another property.
+
+```ts
+const firstEmail = Query.from(users)
+  .select('email')
+  .scalar();
+```
+
+`false` is returned where there is no value.
+
+#### `column()`
+
+It returns the values of the first properties of all objects.
+
+```ts
+const ids = Query.from(users).column();
+```
+
+You can also use it with `select()`:
+
+```ts
+const emails = Query.from(users)
+  .select('email')
+  .column();
+```
+
+#### `values()`
+
+It returns the values of all objects as arrays.
+
+```ts
+const data = Query.from(users)
+  .select(['id', 'email'])
+  .values();
+```
+
+`data` would be something like this:
+
+```ts
+[
+  [1, 'john@icloud.com'],
+  [2, 'mary@gmail.com']
+]
+```
+
+### Ordering results
+
+#### `orderBy(...columns)`
+
+Sorts the results. You can pass multiple arguments to it.
+
+```ts
+  .orderBy('name', 'id')
+```
+
+In the example above, `name` will have more priority than `id`.
+
+It is also possible to apply descending order:
+
+```ts
+const lastId = Query.from(users)
+  .select('id')
+  .orderBy('-id')
+  .scalar();
+```
+
+### Limiting results
+
+#### `limit(limit)`
+
+This method can be used to set a limit of results.
+
+```ts
+  .limit(100)
+```
+
+>Passing a float or a negative number will throw an `InvalidArgumentError`.
+
+#### `skip(numberOfRows)`
+
+Skips the first results.
+
+```ts
+  .skip(5)
+```
+
+Example:
+
+```ts
+const secondId = Query.from(users)
+  .select('id')
+  .skip(1) // skips the first user
+  .scalar();
+```
+
+>Passing a float or a negative number will throw an `InvalidArgumentError`.

package/lib/base-object.d.ts

@@ -0,0 +1,6 @@
+import { PartialOfProperties } from './utils/types';
+export declare abstract class BaseObject {
+    constructor(init?: PartialOfProperties<BaseObject>);
+    setAttribute<K extends keyof this>(attribute: K, value: this[K]): void;
+    setAttributes(attributes: PartialOfProperties<this>): void;
+}

package/lib/base-object.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseObject = void 0;
+class BaseObject {
+    constructor(init = {}) {
+        this.setAttributes(init);
+    }
+    setAttribute(attribute, value) {
+        this[attribute] = value;
+    }
+    setAttributes(attributes) {
+        Object.assign(this, attributes);
+    }
+}
+exports.BaseObject = BaseObject;

package/lib/errors/index.d.ts

@@ -0,0 +1,2 @@
+import { InvalidArgumentError } from './invalid-argument-error';
+export { InvalidArgumentError, };

package/lib/errors/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidArgumentError = void 0;
+const invalid_argument_error_1 = require("./invalid-argument-error");
+Object.defineProperty(exports, "InvalidArgumentError", { enumerable: true, get: function () { return invalid_argument_error_1.InvalidArgumentError; } });

package/lib/errors/invalid-argument-error.d.ts

@@ -0,0 +1,10 @@
+interface InvalidArgumentErrorConfig {
+    method: string;
+    param: string | number;
+    argument: any;
+    expected: string;
+}
+export declare class InvalidArgumentError extends Error {
+    constructor({ method, param, argument, expected }: InvalidArgumentErrorConfig);
+}
+export {};

package/lib/errors/invalid-argument-error.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidArgumentError = void 0;
+class InvalidArgumentError extends Error {
+    constructor({ method, param, argument, expected }) {
+        super(`${argument} is not a valid argument to param ${param} on ${method}(). ` +
+            `It should be ${expected}.`);
+        this.name = 'InvalidArgumentError';
+    }
+}
+exports.InvalidArgumentError = InvalidArgumentError;

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+import { Query } from './query';
+export { Query };

package/lib/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Query = void 0;
+const query_1 = require("./query");
+Object.defineProperty(exports, "Query", { enumerable: true, get: function () { return query_1.Query; } });

package/lib/query-conditions-group-nullable.d.ts

@@ -0,0 +1,4 @@
+import { PropertyOnly } from './utils/types';
+export declare type QueryConditionsGroupNullable<T extends object> = {
+    [P in keyof PropertyOnly<T>]?: T[P] extends object ? QueryConditionsGroupNullable<T[P]> : T[P] | ((value: T[P]) => boolean) | null;
+};

package/lib/query-conditions-group-nullable.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/query-conditions-group.d.ts

@@ -0,0 +1,4 @@
+import { PropertyOnly } from './utils/types';
+export declare type QueryConditionsGroup<T extends object> = {
+    [P in keyof PropertyOnly<T>]?: T[P] extends object ? QueryConditionsGroup<T[P]> : T[P] | ((value: T[P]) => boolean);
+};

package/lib/query-conditions-group.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/query-row-validator.d.ts

@@ -0,0 +1,72 @@
+import { BaseObject } from './base-object';
+import { QueryConditionsGroupNullable } from './query-conditions-group-nullable';
+/**
+ * Validator configuration.
+ */
+interface QueryRowValidatorInitializer<T extends object> {
+    conditionsObject: QueryConditionsGroupNullable<T>;
+    ignoreNullValues: boolean;
+}
+/**
+ * Validates a row in the query.
+ */
+export declare class QueryRowValidator<T extends object> extends BaseObject {
+    /**
+     * Row to be validated.
+     */
+    private row;
+    /**
+     * Conditions to be applied to the row.
+     */
+    private conditionsObject;
+    /**
+     * Indicates whether conditions with `null` and `undefined` values should be
+     * skipped.
+     */
+    private ignoreNullValues;
+    /**
+     * Initializes the validator.
+     *
+     * @param {T} row Row to validated.
+     * @param {QueryRowValidatorInitializer<T>} config Validator configuration.
+     */
+    private constructor();
+    /**
+     * Validates a row.
+     *
+     * @param {T} row Row to validated.
+     * @param {QueryRowValidatorInitializer<T>} config Validator configuration.
+     */
+    static validate<T extends object>(row: T, config: QueryRowValidatorInitializer<T>): boolean;
+    /**
+     * Applies the validation to the row.
+     *
+     * @returns {boolean} `true` if the row is valid, `false` otherwise.
+     */
+    private validate;
+    /**
+     * Validates every condition.
+     *
+     * @returns {boolean} Validation result.
+     */
+    private validateConditions;
+    /**
+     * Validate a condition to a specific column.
+     *
+     * @param {P} columnName Column name.
+     * @param {ColumnCondition<T, P>} condition Condition to be validated.
+     *
+     * @returns {boolean} Validation result.
+     */
+    private validateColumnCondition;
+    /**
+     * Validates an object inside the row.
+     *
+     * @param {object} obj Object to validated.
+     * @param {QueryConditionsGroupNullable<O>} conditionsObject Conditions to be applied to the object.
+     *
+     * @returns {boolean} Validation result.
+     */
+    private validateInnerObject;
+}
+export {};

package/lib/query-row-validator.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryRowValidator = void 0;
+const base_object_1 = require("./base-object");
+const generic_1 = require("./utils/functions/generic");
+const type_guards_1 = require("./utils/functions/type-guards");
+/**
+ * Validates a row in the query.
+ */
+class QueryRowValidator extends base_object_1.BaseObject {
+    /**
+     * Initializes the validator.
+     *
+     * @param {T} row Row to validated.
+     * @param {QueryRowValidatorInitializer<T>} config Validator configuration.
+     */
+    constructor(row, config) {
+        super({ row, ...config });
+    }
+    /**
+     * Validates a row.
+     *
+     * @param {T} row Row to validated.
+     * @param {QueryRowValidatorInitializer<T>} config Validator configuration.
+     */
+    static validate(row, config) {
+        return new QueryRowValidator(row, config).validate();
+    }
+    /**
+     * Applies the validation to the row.
+     *
+     * @returns {boolean} `true` if the row is valid, `false` otherwise.
+     */
+    validate() {
+        return this.validateConditions();
+    }
+    /**
+     * Validates every condition.
+     *
+     * @returns {boolean} Validation result.
+     */
+    validateConditions() {
+        const conditionsEntries = (0, generic_1.getEntries)(this.conditionsObject);
+        return conditionsEntries.every(([columnName, condition]) => this.validateColumnCondition(columnName, condition));
+    }
+    /**
+     * Validate a condition to a specific column.
+     *
+     * @param {P} columnName Column name.
+     * @param {ColumnCondition<T, P>} condition Condition to be validated.
+     *
+     * @returns {boolean} Validation result.
+     */
+    validateColumnCondition(columnName, condition) {
+        if (this.ignoreNullValues && (condition === null || condition === undefined)) {
+            return true;
+        }
+        const cellValue = this.row[columnName];
+        if ((0, type_guards_1.isFunction)(condition)) {
+            return condition(cellValue);
+        }
+        if (Array.isArray(condition)) {
+            return Array.isArray(cellValue) ? (0, generic_1.compareArrays)(cellValue, condition) : false;
+        }
+        if ((0, type_guards_1.isObject)(condition)) {
+            return (0, type_guards_1.isObject)(cellValue) ? this.validateInnerObject(cellValue, condition) : false;
+        }
+        return cellValue === condition;
+    }
+    /**
+     * Validates an object inside the row.
+     *
+     * @param {object} obj Object to validated.
+     * @param {QueryConditionsGroupNullable<O>} conditionsObject Conditions to be applied to the object.
+     *
+     * @returns {boolean} Validation result.
+     */
+    validateInnerObject(obj, conditionsObject) {
+        return QueryRowValidator.validate(obj, {
+            conditionsObject,
+            ignoreNullValues: this.ignoreNullValues,
+        });
+    }
+}
+exports.QueryRowValidator = QueryRowValidator;