@rwillians/qx 0.1.2 → 0.1.3

package/dist/esm/index.js

@@ -0,0 +1,660 @@
+import * as std from './standard-schema';
+import * as u from './utils';
+// // // // // // // // // // // // // // // // // // // // // // // //
+//                              SYMBOLS                              //
+// // // // // // // // // // // // // // // // // // // // // // // //
+/**
+ * @private Symbol used to store the table name on aliased tables.
+ * @since   0.1.0
+ * @version 1
+ */
+const TABLE_NAME = Symbol.for('~exto.table-name');
+/**
+ * @private Symbol used to store the table alias on aliased tables.
+ * @since   0.1.0
+ * @version 1
+ */
+const TABLE_ALIAS = Symbol.for('~exto.table-alias');
+/**
+ * @private A builder for column properties.
+ * @since   0.1.0
+ * @version 1
+ */
+class ColumnPropsBuilder {
+    props;
+    constructor(props) {
+        this.props = props;
+    }
+    /**
+     * @public  Marks the column as autoincrementing.
+     * @since   0.1.0
+     * @version 1
+     */
+    autoincrement() {
+        if (this.props.type !== 'INTEGER')
+            throw new Error('Autoincrement can only be set on integer columns');
+        return new ColumnPropsBuilder({ ...this.props, autoincrement: true });
+    }
+    /**
+     * @public  Sets a default value for the column.
+     * @since   0.1.0
+     * @version 1
+     */
+    default(value) {
+        return new ColumnPropsBuilder({ ...this.props, default: value });
+    }
+    /**
+     * @public  Marks the column as nullable.
+     * @since   0.1.0
+     * @version 1
+     * @throws {Error} if the column is a primary key.
+     */
+    nullable() {
+        if (this.props.primaryKey)
+            throw new Error('Cannot set nullable on a primary key column');
+        const { schema, ...props } = this.props;
+        return new ColumnPropsBuilder({ ...props, nullable: true, schema: std.nullable(schema) });
+    }
+    /**
+     * @public  Marks the column as a primary key.
+     * @since   0.1.0
+     * @version 1
+     * @throws {Error} if the column is nullable.
+     */
+    primaryKey() {
+        if (this.props.nullable)
+            throw new Error('Cannot make a nullable column a primary key');
+        return new ColumnPropsBuilder({ ...this.props, primaryKey: true });
+    }
+}
+/**
+ * @public  A way to define a column with a custom standard schema.
+ * @since   0.1.0
+ * @version 1
+ */
+const defineColumn = (baseProps) => new ColumnPropsBuilder(baseProps);
+/**
+ * @public  Built-in column types.
+ * @since   0.1.0
+ * @version 1
+ */
+const types = {
+    /**
+     * @public  Defines a column type that accepts binary data.
+     * @since   0.1.0
+     * @version 1
+     */
+    binary: () => defineColumn({
+        type: 'BINARY',
+        schema: std.instanceOf(Uint8Array),
+    }),
+    /**
+     * @public  Defines a column type that accepts boolean values.
+     * @since   0.1.0
+     * @version 1
+     */
+    boolean: () => defineColumn({
+        type: 'BOOLEAN',
+        schema: std.boolean(),
+    }),
+    /**
+     * @public  Defines a column type that accepts a Date object, an
+     *          ISO 8601 date string, or a Unix timestamp in milliseconds.
+     * @since   0.1.0
+     * @version 1
+     */
+    datetime: () => defineColumn({
+        type: 'DATETIME',
+        schema: std.date(),
+    }),
+    /**
+     * @public  Defines a column type that accepts floating-point numbers.
+     * @since   0.1.0
+     * @version 1
+     */
+    float: () => defineColumn({
+        type: 'FLOAT',
+        schema: std.number({ min: Number.MIN_VALUE, max: Number.MAX_VALUE }),
+    }),
+    /**
+     * @public  Defines a column type that accepts integer numbers.
+     * @since   0.1.0
+     * @version 1
+     */
+    integer: () => defineColumn({
+        type: 'INTEGER',
+        schema: std.integer({ min: Number.MIN_SAFE_INTEGER, max: Number.MAX_SAFE_INTEGER }),
+    }),
+    /**
+     * @public  Defines a column type that accepts small strings (VARCHAR,
+     *          up to 255 characters).
+     * @since   0.1.0
+     * @version 1
+     * @throws {Error} if the specified size is greater than 255.
+     */
+    string: ({ size = 255 } = {}) => defineColumn({
+        type: 'VARCHAR',
+        schema: std.string({ max: u.lte(size, 255) }),
+        size,
+    }),
+    /**
+     * @public  Defines a column type that accepts large strings (TEXT).
+     * @since   0.1.0
+     * @version 1
+     */
+    text: () => defineColumn({
+        type: 'TEXT',
+        schema: std.string(),
+    }),
+};
+/**
+ * @private  Creates the `as` function for aliasing a table.
+ * @since   0.1.0
+ * @version 1
+ */
+const aliasedTableFn = (table) => (alias) => {
+    const columns = Object.fromEntries(Object
+        .entries(table.columns)
+        .map(([cname, col]) => [cname, { ...col, table: alias }]));
+    return { [TABLE_NAME]: table.name, [TABLE_ALIAS]: alias, ...columns };
+};
+/**
+ * @public  Defines a new table.
+ * @since   0.1.0
+ * @version 1
+ */
+const defineTable = (tname, shapeFn) => {
+    const columns = Object.fromEntries(Object
+        .entries(shapeFn(types))
+        .map(([cname, { props }]) => [cname, { ...props, name: cname, table: tname }]));
+    const table = { name: tname, columns };
+    return { ...table, as: aliasedTableFn(table) };
+};
+/**
+ * @public  Expression builders.
+ * @since   0.1.0
+ * @version 1
+ */
+const expr = {
+    // // // // // // // // // // // // // // // // // // // // // // //
+    //                     BINARY OP EXPRESSIONS                      //
+    // // // // // // // // // // // // // // // // // // // // // // //
+    /**
+     * @public  Builds an equality expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    eq: (lhs, rhs) => ({ lhs, op: '=', rhs }),
+    /**
+     * @public Builds a not-equal expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    ne: (lhs, rhs) => ({ lhs, op: '!=', rhs }),
+    /**
+     * @public Builds a less-than expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    lt: (lhs, rhs) => ({ lhs, op: '<', rhs }),
+    /**
+     * @public Builds a less-than-or-equal expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    lte: (lhs, rhs) => ({ lhs, op: '<=', rhs }),
+    /**
+     * @public Builds a greater-than expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    gt: (lhs, rhs) => ({ lhs, op: '>', rhs }),
+    /**
+     * @public Builds a greater-than-or-equal expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    gte: (lhs, rhs) => ({ lhs, op: '>=', rhs }),
+    /**
+     * @public Builds a LIKE expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    like: (lhs, rhs) => ({ lhs, op: 'LIKE', rhs }),
+    /**
+     * @public Builds a NOT LIKE expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    notLike: (lhs, rhs) => ({ lhs, op: 'NOT LIKE', rhs }),
+    /**
+     * @public Builds an IN expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    in: (lhs, rhs) => ({ lhs, op: 'IN', rhs }),
+    /**
+     * @public Builds a NOT IN expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    notIn: (lhs, rhs) => ({ lhs, op: 'NOT IN', rhs }),
+    /**
+     * @public Builds an IS expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    is: (lhs, rhs) => ({ lhs, op: 'IS', rhs }),
+    /**
+     * @public Builds an IS NOT expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    isNot: (lhs, rhs) => ({ lhs, op: 'IS NOT', rhs }),
+    // // // // // // // // // // // // // // // // // // // // // // //
+    //                     BOOLEAN OP EXPRESSIONS                     //
+    // // // // // // // // // // // // // // // // // // // // // // //
+    /**
+     * @public Builds an AND expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    and: (exprs) => ({ and: exprs }),
+    /**
+     * @public Builds an OR expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    or: (exprs) => ({ or: exprs }),
+    /**
+     * @public Builds a NOT expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    not: (expr) => ({ not: expr }),
+};
+/**
+ * @public  Expression type guards.
+ * @since   0.1.0
+ * @version 1
+ */
+const is = {
+    // // // // // // // // // // // // // // // // // // // // // // //
+    //                     BINARY OP EXPRESSIONS                      //
+    // // // // // // // // // // // // // // // // // // // // // // //
+    /**
+     * @public  Checks whether the given value is a binary op expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    binaryOp: (expr) => u.isPlainObject(expr) && 'op' in expr && 'lhs' in expr && 'rhs' in expr,
+    /**
+     * @public  Checks whether the given value is an equality expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    eq: (expr) => u.isPlainObject(expr) && 'op' in expr && expr.op === '=',
+    /**
+     * @public  Checks whether the given value is a not-equal expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    ne: (expr) => u.isPlainObject(expr) && 'op' in expr && expr.op === '!=',
+    /**
+     * @public  Checks whether the given value is a less-than expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    lt: (expr) => u.isPlainObject(expr) && 'op' in expr && expr.op === '<',
+    /**
+     * @public  Checks whether the given value is a less-than-or-equal expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    lte: (expr) => u.isPlainObject(expr) && 'op' in expr && expr.op === '<=',
+    /**
+     * @public  Checks whether the given value is a greater-than expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    gt: (expr) => u.isPlainObject(expr) && 'op' in expr && expr.op === '>',
+    /**
+     * @public  Checks whether the given value is a greater-than-or-equal expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    gte: (expr) => u.isPlainObject(expr) && 'op' in expr && expr.op === '>=',
+    /**
+     * @public  Checks whether the given value is a LIKE expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    like: (expr) => u.isPlainObject(expr) && 'op' in expr && expr.op === 'LIKE',
+    /**
+     * @public  Checks whether the given value is a NOT LIKE expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    notLike: (expr) => u.isPlainObject(expr) && 'op' in expr && expr.op === 'NOT LIKE',
+    /**
+     * @public  Checks whether the given value is an IN expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    in: (expr) => u.isPlainObject(expr) && 'op' in expr && expr.op === 'IN',
+    /**
+     * @public  Checks whether the given value is a NOT IN expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    notIn: (expr) => u.isPlainObject(expr) && 'op' in expr && expr.op === 'NOT IN',
+    /**
+     * @public  Checks whether the given value is an IS expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    is: (expr) => u.isPlainObject(expr) && 'is' in expr,
+    // // // // // // // // // // // // // // // // // // // // // // //
+    //                     BOOLEAN OP EXPRESSIONS                     //
+    // // // // // // // // // // // // // // // // // // // // // // //
+    /**
+     * @public  Checks whether the given value is an AND expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    and: (expr) => u.isPlainObject(expr) && 'and' in expr,
+    /**
+     * @public  Checks whether the given value is an OR expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    or: (expr) => u.isPlainObject(expr) && 'or' in expr,
+    /**
+     * @public  Checks whether the given value is a NOT expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    not: (expr) => u.isPlainObject(expr) && 'not' in expr,
+    // // // // // // // // // // // // // // // // // // // // // // //
+    //                            LITERALS                            //
+    // // // // // // // // // // // // // // // // // // // // // // //
+    /**
+     * @public  Checks whether the given value is a boolean literal.
+     * @since   0.1.0
+     * @version 1
+     */
+    boolean: (value) => typeof value === 'boolean',
+    /**
+     * @public  Checks whether the given value is a date literal.
+     * @since   0.1.0
+     * @version 1
+     */
+    date: (value) => value instanceof Date,
+    /**
+     * @public  Checks whether the given value is a null literal.
+     * @since   0.1.0
+     * @version 1
+     */
+    null: (expr) => expr === null,
+    /**
+     * @public  Checks whether the given value is a number literal.
+     * @since   0.1.0
+     * @version 1
+     */
+    number: (expr) => typeof expr === 'number',
+    /**
+     * @public  Checks whether the given value is a string literal.
+     * @since   0.1.0
+     * @version 1
+     */
+    string: (expr) => typeof expr === 'string',
+    // // // // // // // // // // // // // // // // // // // // // // //
+    //                             OTHERS                             //
+    // // // // // // // // // // // // // // // // // // // // // // //
+    /**
+     * @public  Checks whether the given value is a literal expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    literal: (expr) => expr === null || expr instanceof Date || ['boolean', 'number', 'string'].includes(typeof expr),
+    /**
+     * @public  Checks whether the given value is a column expression.
+     * @since   0.1.0
+     * @version 1
+     */
+    column: (expr) => u.isPlainObject(expr) && 'type' in expr && 'schema' in expr,
+};
+;
+;
+// // // // // // // // // // // // // // // // // // // // // // // //
+//                         CREATE STATEMENTS                         //
+// // // // // // // // // // // // // // // // // // // // // // // //
+/**
+ * @public  Create statement builder.
+ * @since   0.1.0
+ * @version 1
+ */
+const create = {
+    /**
+     * @public  Prepares a create table statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    table: (table, options = {}) => ({
+        /**
+         * @public  Executes the create table statement onto the given
+         *          database.
+         * @since   0.1.0
+         * @version 1
+         */
+        onto: async (db) => db.createTable({
+            ...options,
+            table: table.name,
+            columns: Object.values(table.columns),
+        }),
+    }),
+};
+// // // // // // // // // // // // // // // // // // // // // // // //
+//                         INSERT STATEMENT                          //
+// // // // // // // // // // // // // // // // // // // // // // // //
+/**
+ * @private Resolves the value of a column before insertion. This is
+ *          where default values are applied if the column is either
+ *          missing or nullish.
+ * @since   0.1.0
+ * @version 1
+ */
+const resolveInsertValue = (column, row) => {
+    if (column.default)
+        return row[column.name] ?? u.resolve(column.default);
+    // ↓ it's ok to omit nullable columns, let's make it null if undefined
+    if (column.nullable)
+        return row[column.name] ?? null;
+    return row[column.name];
+};
+/**
+ * @private Prepares a row for insertion. Only known fields are kept,
+ *          additional fields get disposed of.
+ * @since   0.1.0
+ * @version 1
+ */
+const prepareForInsert = (shape) => (row) => Object.fromEntries(Object
+    .entries(shape)
+    .map(([key, column]) => [key, resolveInsertValue(column, row)]));
+/**
+ * @private Takes from the given table only the columns that can be
+ *          present on insertion. It excludes, for example,
+ *          autoincrement columns.
+ * @since   0.1.0
+ * @version 1
+ */
+const getInsertShape = (table) => Object.fromEntries(Object
+    .entries(table.columns)
+    .filter(([_, col]) => !col.autoincrement));
+/**
+ * @private Builds the standard schema to be used to parse / validate
+ *          rows before insertion.
+ * @since   0.1.0
+ * @version 1
+ */
+const buildInsertSchema = (shape) => std.strictObject(u.mapValues(shape, (column) => column.schema));
+/**
+ * @public  Insert statement builder.
+ * @since   0.1.0
+ * @version 1
+ */
+class InsertBuilder {
+    table;
+    rows;
+    constructor(table, rows = []) {
+        this.table = table;
+        this.rows = rows;
+    }
+    /**
+     * @public  Adds one or more rows to be inserted.
+     * @since   0.1.0
+     * @version 1
+     */
+    insert(rows) {
+        this.rows.push(...(u.wrap(rows)));
+        return this;
+    }
+    /**
+     * @public  Executes the insert statement onto the given database.
+     * @since   0.1.0
+     * @version 1
+     */
+    async run(db) {
+        if (this.rows.length === 0)
+            return [];
+        const insertShape = getInsertShape(this.table);
+        const schema = std.array(buildInsertSchema(insertShape));
+        const result = std.parse(schema, this.rows.map(prepareForInsert(insertShape)));
+        if (result.issues)
+            throw new Error('Failed validation: ' + JSON.stringify(result.issues, null, 2));
+        const rows = await db.insert({
+            table: this.table.name,
+            records: result.value,
+            insertShape,
+            returnShape: this.table.columns,
+        });
+        return rows;
+    }
+    ;
+}
+/**
+ * @public  Starts an insert statement for the given table.
+ * @since   0.1.0
+ * @version 1
+ */
+const into = (table) => new InsertBuilder(table);
+/**
+ * @private Transforms a {@link Query} into a {@link SelectStatement}.
+ * @since   0.1.0
+ * @version 1
+ */
+const toSelectStatement = (query) => ({
+    ...query,
+    registry: u.mapValues(query.registry, table => table[TABLE_NAME]),
+});
+/**
+ * @public  Select statement builder with a fluent API.
+ *
+ *          We only need to keep track of two types in here:
+ *          - the registry of aliased tables, so they can be
+ *            referenced in expressions and selection; and
+ *          - the selected columns, so we can infer the returning
+ *            type of the query.
+ * @since   0.1.0
+ * @version 1
+ */
+class QueryBuilder {
+    query;
+    constructor(query) {
+        this.query = query;
+    }
+    /**
+     * @public  Executes the select statement against the given database,
+     *          returning all matching rows.
+     * @since   0.1.0
+     * @version 1
+     */
+    async all(db) {
+        // @TODO calls query engine with the query object
+        return db.query(toSelectStatement(this.query));
+    }
+    /**
+     * @public  Sets a limit on the number of rows to be returned.
+     * @since   0.1.0
+     * @version 1
+     */
+    limit(n) {
+        return new QueryBuilder({ ...this.query, limit: n });
+    }
+    /**
+     * @public  Sets an offset for the rows to be returned.
+     * @since   0.1.0
+     * @version 1
+     */
+    offset(n) {
+        return new QueryBuilder({ ...this.query, offset: n });
+    }
+    /**
+     * @public  Executes the select statement against the given database,
+     *          returning the first matching row.
+     * @since   0.1.0
+     * @version 1
+     */
+    async one(db) {
+        // @TODO calls query engine with the query object
+        const op = toSelectStatement({ ...this.query, limit: 1, offset: 0 });
+        const rows = await db.query(op);
+        if (rows.length === 0)
+            return null;
+        return rows[0];
+    }
+    /**
+     * @public  Defines the order by clause of the query.
+     * @since   0.1.0
+     * @version 1
+     */
+    orderBy(fn) {
+        return new QueryBuilder({ ...this.query, orderBy: fn(this.query.registry) });
+    }
+    /**
+     * @public  Defines the selection of the query.
+     * @since   0.1.0
+     * @version 1
+     */
+    select(fn) {
+        return new QueryBuilder({ ...this.query, select: fn(this.query.registry) });
+    }
+    /**
+     * @public  Defines the where clause of the query. If there's already
+     *          a WHERE clause in the query, the new clause will be
+     *          ANDed to the existing one.
+     * @since   0.1.0
+     * @version 1
+     */
+    where(fn) {
+        const value = fn(this.query.registry);
+        const where = this.query.where === undefined ? value
+            : is.and(this.query.where) ? expr.and([...this.query.where.and, value])
+                : expr.and([this.query.where, value]);
+        return new QueryBuilder({ ...this.query, where });
+    }
+}
+/**
+ * @public  Starts a select statement from the given table.
+ * @since   0.1.0
+ * @version 1
+ */
+const from = (table) => new QueryBuilder({
+    registry: { [table[TABLE_ALIAS]]: table },
+    from: table[TABLE_ALIAS],
+    select: { ...table },
+});
+// // // // // // // // // // // // // // // // // // // // // // // //
+//                              EXPORTS                              //
+// // // // // // // // // // // // // // // // // // // // // // // //
+export { create, defineTable as table, expr, from, into, is, types as t, };

package/dist/esm/pretty-logger.d.ts

@@ -0,0 +1,7 @@
+import { type ILogger } from './index';
+/**
+ * @public  Creates a basic console logger that logs all queries.
+ * @since   0.1.0
+ * @version 1
+ */
+export declare const createPrettyLogger: () => ILogger;

package/dist/esm/pretty-logger.js

@@ -0,0 +1,11 @@
+import { inspect } from 'node:util';
+import { highlight } from 'sql-highlight';
+import {} from './index';
+/**
+ * @public  Creates a basic console logger that logs all queries.
+ * @since   0.1.0
+ * @version 1
+ */
+export const createPrettyLogger = () => ({
+    debug: (sql, params) => { process.stdout.write(highlight(sql) + ' ' + inspect(params, false, null, true) + '\n'); },
+});