@rwillians/qx 0.1.20 → 0.1.21

package/dist/esm/bun-sqlite.js

@@ -0,0 +1,512 @@
+import { Database } from 'bun:sqlite';
+import { inspect } from 'node:util';
+import * as u from './utils';
+import { is, withLoggedQuery, } from './adapter';
+/**
+ * @private Mapping of qx's primitive types to SQLite native types.
+ * @since   0.1.0
+ * @version 1
+ */
+const TYPES_MAPPING = {
+    BINARY: () => 'BLOB',
+    BOOLEAN: () => 'INTEGER',
+    DATETIME: () => 'INTEGER',
+    FLOAT: () => 'REAL',
+    INTEGER: () => 'INTEGER',
+    TEXT: () => 'TEXT',
+    VARCHAR: () => `TEXT`,
+};
+/**
+ * @private Registry of codecs for Bun SQLite.
+ * @since   0.1.0
+ * @version 1
+ */
+const CODECS = {
+    BINARY: {
+        encode: (value) => value,
+        decode: (value) => value,
+    },
+    BOOLEAN: {
+        encode: (value) => (value ? 1 : 0),
+        decode: (value) => value === 1,
+    },
+    DATETIME: {
+        encode: (value) => value.valueOf(),
+        decode: (value) => new Date(value),
+    },
+    FLOAT: {
+        encode: (value) => value * 1.0,
+        decode: (value) => value * 1.0,
+    },
+    INTEGER: {
+        encode: (value) => ~~value, // ← nifty little trick to truncate to integer
+        decode: (value) => ~~value,
+    },
+    TEXT: {
+        encode: (value) => value,
+        decode: (value) => value,
+    },
+    VARCHAR: {
+        encode: (value) => value,
+        decode: (value) => value,
+    },
+};
+/**
+ * @private An empty rendered result.
+ * @since   0.1.0
+ * @version 1
+ */
+const EMPTY_RENDER_RESULT = { frags: [], params: [] };
+/**
+ * @private A function combinator that accumulates rendered fragments
+ *          and parameters when used in a reduce operation.
+ * @since   0.1.0
+ * @version 1
+ */
+const collect = (fn) => (acc, value) => {
+    const result = fn(value);
+    return { frags: [...acc.frags, ...result.frags], params: [...acc.params, ...result.params] };
+};
+/**
+ * @private A function combinator that glues rendered fragments
+ *          together.
+ * @since   0.1.0
+ * @version 1
+ */
+const glue = (fn) => (...args) => {
+    const result = fn(...args);
+    return { frags: [result.frags.join('')], params: result.params };
+};
+/**
+ * @private Functions for rendering fragments while generateing DDL.
+ * @since   0.1.0
+ * @version 1
+ */
+const render = {
+    /**
+     * @private Renders an object reference (e.g., table name, column
+     *          name, etc).
+     * @since   0.1.0
+     * @version 1
+     */
+    ref: (value) => `"${value}"`,
+    /**
+     * @private Renders a column definition, for the create table
+     *          statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    column: glue((col) => {
+        const { name, primaryKey = false, autoincrement = false, nullable = false, unique = false, } = col;
+        const type = TYPES_MAPPING[col.type](col);
+        // @TODO DDL should not have to know that it needs to snake_case here
+        const frags = [render.ref(u.snakeCase(name)), type];
+        if (primaryKey)
+            frags.push('PRIMARY KEY ASC');
+        if (autoincrement)
+            frags.push('AUTOINCREMENT');
+        if (primaryKey)
+            return { frags: [frags.join(' ')], params: [] };
+        if (!nullable)
+            frags.push('NOT NULL');
+        if (unique)
+            frags.push('UNIQUE');
+        return { frags: [frags.join(' ')], params: [] };
+    }),
+    /**
+     * @private Renders a value placeholder for an insert statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    row: (shape) => glue((record) => {
+        const frags = [];
+        const params = [];
+        for (const key of Object.keys(shape)) {
+            frags.push('?');
+            params.push(record[key]);
+        }
+        return { frags: ['(' + frags.join(', ') + ')'], params };
+    }),
+    /**
+     * @private Renders the columns of a query's selection.
+     * @since   0.1.0
+     * @version 1
+     */
+    selection: glue((selection) => {
+        const frags = Object
+            .entries(selection)
+            // @TODO DDL should not have to know that it needs to snake_case here
+            .map(([alias, col]) => `${render.expr.column(col).frags.join('')} AS ${render.ref(alias)}`);
+        return { frags: [frags.join(', ')], params: [] };
+    }),
+    /**
+     * @private Renders an order by clause.
+     * @since   0.1.0
+     * @version 1
+     *
+     * Not using {@link glue} here becuase it's breaking typescript
+     * ¯\_(ツ)_/¯
+     */
+    orderBy: ([expr, dir]) => {
+        const { frags, params } = render.expr.any(expr);
+        return { frags: [[...frags, dir].join(' ')], params };
+    },
+    /**
+     * @private Renders a join clause.
+     * @since   0.1.9
+     * @version 1
+     */
+    join: glue((join) => {
+        const result = render.expr.any(join.on);
+        return {
+            frags: [' ', join.type, ' ', render.ref(join.table), ' AS ', render.ref(join.alias), ' ON ', ...result.frags],
+            params: result.params,
+        };
+    }),
+    /**
+     * @private Expression rendering functions.
+     * @since   0.1.0
+     * @version 1
+     */
+    expr: {
+        /**
+         * @private Renders any {@link Expr}.
+         * @since   0.1.0
+         * @version 1
+         */
+        any: glue((value) => {
+            if (is.binaryOp(value))
+                return render.expr.binaryOp(value);
+            if (is.and(value))
+                return render.expr.and(value);
+            if (is.or(value))
+                return render.expr.or(value);
+            if (is.not(value))
+                return render.expr.not(value);
+            if (is.column(value))
+                return render.expr.column(value);
+            if (is.literal(value))
+                return render.expr.literal(value);
+            throw new Error(`Unsupported expression type: ${inspect(value)}`);
+        }),
+        // // // // // // // // // // // // // // // // // // // // // //
+        //                    BINARY OP EXPRESSIONS                    //
+        // // // // // // // // // // // // // // // // // // // // // //
+        /**
+         * @private Renders any binary op expression.
+         * @since   0.1.0
+         * @version 1
+         */
+        binaryOp: glue((value) => {
+            const lhs = render.expr.any(value.lhs);
+            const rhs = Array.isArray(value.rhs)
+                ? render.expr.array(value.rhs)
+                : render.expr.any(value.rhs);
+            return { frags: ['(', ...lhs.frags, ` ${value.op} `, ...rhs.frags, ')'], params: [...lhs.params, ...rhs.params] };
+        }),
+        // // // // // // // // // // // // // // // // // // // // // //
+        //                   BOOLEAN OP EXPRESSIONS                    //
+        // // // // // // // // // // // // // // // // // // // // // //
+        /**
+         * @private Renders an AND expression.
+         * @since   0.1.0
+         * @version 1
+         */
+        and: glue((value) => {
+            const inner = value.and.reduce(collect(render.expr.any), EMPTY_RENDER_RESULT);
+            return { frags: ['(', inner.frags.join(' AND '), ')'], params: inner.params };
+        }),
+        /**
+         * @private Renders an OR expression.
+         * @since   0.1.0
+         * @version 1
+         */
+        or: glue((value) => {
+            const inner = value.or.reduce(collect(render.expr.any), EMPTY_RENDER_RESULT);
+            return { frags: ['(', inner.frags.join(' OR '), ')'], params: inner.params };
+        }),
+        /**
+         * @private Renders a NOT expression.
+         * @since   0.1.0
+         * @version 1
+         */
+        not: glue((value) => {
+            const inner = render.expr.any(value.not);
+            return { frags: ['NOT ', ...inner.frags], params: inner.params };
+        }),
+        // // // // // // // // // // // // // // // // // // // // // //
+        //                      OTHER EXPRESSIONS                      //
+        // // // // // // // // // // // // // // // // // // // // // //
+        array: glue((values) => {
+            const { frags, params } = values.reduce(collect(render.expr.any), EMPTY_RENDER_RESULT);
+            return { frags: ['(', frags.join(', '), ')'], params };
+        }),
+        /**
+         * @private Renders a column expression.
+         * @since   0.1.0
+         * @version 1
+         */
+        column: glue((col) => ({
+            // @TODO DDL should not have to know that it needs to snake_case here
+            frags: [`${render.ref(col.table)}.${render.ref(u.snakeCase(col.name))}`],
+            params: [],
+        })),
+        /**
+         * @private Renders a literal expression.
+         * @since   0.1.0
+         * @version 1
+         */
+        literal: glue((value) => {
+            if (is.null(value))
+                return render.expr.null();
+            if (is.boolean(value))
+                return render.expr.boolean(value);
+            if (is.date(value))
+                return render.expr.date(value);
+            if (is.number(value))
+                return render.expr.number(value);
+            if (is.string(value))
+                return render.expr.string(value);
+            throw new Error(`Unsupported literal expression: ${inspect(value)}`);
+        }),
+        // // // // // // // // // // // // // // // // // // // // // //
+        //                          LITERALS                           //
+        // // // // // // // // // // // // // // // // // // // // // //
+        /**
+         * @private Renders a boolean literal expression.
+         * @since   0.1.0
+         * @version 1
+         */
+        boolean: glue((value) => ({
+            frags: [value ? 'TRUE' : 'FALSE'],
+            params: [],
+        })),
+        /**
+         * @private Renders a date literal expression.
+         * @since   0.1.0
+         * @version 1
+         */
+        date: glue((value) => ({
+            frags: ['?'],
+            params: [CODECS.DATETIME.encode(value)],
+        })),
+        /**
+         * @private Renders a null literal expression.
+         * @since   0.1.0
+         * @version 1
+         */
+        null: glue(() => ({ frags: ['NULL'], params: [] })),
+        /**
+         * @private Renders a number literal expression.
+         * @since   0.1.0
+         * @version 1
+         */
+        number: glue((value) => ({ frags: ['?'], params: [value] })),
+        /**
+         * @private Renders a string literal expression.
+         * @since   0.1.0
+         * @version 1
+         */
+        string: glue((value) => ({ frags: ['?'], params: [value] })),
+    },
+};
+/**
+ * @private DDL generation functions.
+ * @since   0.1.0
+ * @version 1
+ */
+const ddl = {
+    /**
+     * @private Generates DDL for create table statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    createTable: (op) => {
+        const columns = op
+            .columns
+            .map(col => render.column(col).frags.join(''))
+            .join(', ');
+        const frags = [
+            'CREATE ',
+            (op.unlogged ? 'UNLOGGED ' : ''),
+            'TABLE ',
+            (op.ifNotExists ? 'IF NOT EXISTS ' : ''),
+            render.ref(op.table),
+            ' (',
+            ...columns,
+            ');',
+        ];
+        return { sql: frags.join(''), params: [] };
+    },
+    /**
+     * @private Generates DDL for insert statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    insert: (op) => {
+        const values = op
+            .records
+            .reduce(collect(render.row(op.insertShape)), EMPTY_RENDER_RESULT);
+        const frags = [
+            'INSERT INTO ',
+            render.ref(op.table),
+            ' (',
+            Object.keys(op.insertShape).map(render.ref).join(', '),
+            ') VALUES ',
+            values.frags.join(', '),
+            ' RETURNING ',
+            render.selection(op.returnShape).frags.join(', '),
+            ';'
+        ];
+        return { sql: frags.join(''), params: values.params };
+    },
+    /**
+     * @private Generates DDL for select statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    select: (op) => {
+        const joins = op.joins && op.joins.length > 0
+            ? op.joins.reduce(collect(render.join), EMPTY_RENDER_RESULT)
+            : EMPTY_RENDER_RESULT;
+        const where = op.where
+            ? render.expr.any(op.where)
+            : EMPTY_RENDER_RESULT;
+        const orderBy = op.orderBy && op.orderBy.length > 0
+            ? op.orderBy.reduce(collect(render.orderBy), EMPTY_RENDER_RESULT)
+            : EMPTY_RENDER_RESULT;
+        const limit = op.limit !== undefined
+            ? { frags: [' LIMIT ', '?'], params: [op.limit] }
+            : EMPTY_RENDER_RESULT;
+        const offset = op.offset !== undefined
+            ? { frags: [' OFFSET ', '?'], params: [op.offset] }
+            : EMPTY_RENDER_RESULT;
+        const frags = [
+            'SELECT ',
+            render.selection(op.select).frags.join(', '),
+            ' FROM ',
+            render.ref(op.registry[op.from]),
+            ' AS ',
+            render.ref(op.from),
+            ...joins.frags,
+            (where.frags.length > 0 ? ' WHERE ' : ''),
+            ...where.frags,
+            (orderBy.frags.length > 0 ? ' ORDER BY ' + orderBy.frags.join(', ') : ''),
+            ...limit.frags,
+            ...offset.frags,
+            ';'
+        ];
+        return { sql: frags.join(''), params: [...joins.params, ...where.params, ...limit.params, ...offset.params] };
+    },
+};
+/**
+ * @private Creates an encoder function that converts a row into the
+ *          expected shape and format expected by the database.
+ * @since   0.1.0
+ * @version 1
+ */
+const createEncoder = (shape) => {
+    const encoders = Object.fromEntries(Object
+        .entries(shape)
+        .map(([key, col]) => [key, (value) => value === null ? null : CODECS[col.type].encode(value)]));
+    return (row) => Object.fromEntries(Object
+        .entries(encoders)
+        .map(([key, encode]) => [u.snakeCase(key), encode(row[key])]));
+};
+/**
+ * @private Creates a decoder function that converts a database row
+ *          into the shape and format expected by the application.
+ * @since   0.1.0
+ * @version 1
+ */
+const createDecoder = (shape) => {
+    const decoders = Object.fromEntries(Object
+        .entries(shape)
+        .map(([key, col]) => [key, (value) => value === null ? null : CODECS[col.type].decode(value)]));
+    return (row) => Object.fromEntries(Object
+        .entries(decoders)
+        .map(([key, decode]) => [key, decode(row[key])]));
+};
+/**
+ * @private Bun SQLite database adapter implementation.
+ * @since   0.1.0
+ * @version 1
+ */
+class BunSQLite {
+    conn;
+    loggers;
+    constructor(conn, loggers = []) {
+        this.conn = conn;
+        this.loggers = loggers;
+    }
+    /**
+     * @public  Attaches a logger to the database instance.
+     * @since   0.1.0
+     * @version 1
+     */
+    attachLogger(logger) {
+        this.loggers.push(logger);
+        return this;
+    }
+    /**
+     * @public  Executes a create table statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    async createTable(op) {
+        const { sql, params } = ddl.createTable(op);
+        await withLoggedQuery(this.loggers, { sql, params }, () => this.conn.run(sql));
+    }
+    /**
+     * @public  Executes an insert statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    async insert(op) {
+        const { sql, params } = ddl.insert({
+            ...op,
+            records: op.records.map(createEncoder(op.insertShape)),
+            insertShape: u.mapKeys(op.insertShape, u.snakeCase),
+        });
+        const rows = await withLoggedQuery(this.loggers, { sql, params }, () => this.conn
+            .prepare(sql)
+            .all(...params));
+        return rows.map(createDecoder(op.returnShape));
+    }
+    /**
+     * @public  Executes a select statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    async query(op) {
+        const { sql, params } = ddl.select(op);
+        const rows = await withLoggedQuery(this.loggers, { sql, params }, () => this.conn
+            .prepare(sql)
+            .all(...params));
+        return rows.map(createDecoder(op.select));
+    }
+    /**
+     * @public  Executes a function within a transaction.
+     * @since   0.1.10
+     * @version 1
+     */
+    async transaction(fn) {
+        return this.conn.transaction(fn)();
+    }
+}
+/**
+ * @public  Creates a connection to the database.
+ * @since   0.1.0
+ * @version 1
+ */
+const connect = (...args) => new BunSQLite(new Database(...args));
+/**
+ * @public  Creates a connection to an in-memory database.
+ * @since   0.1.12
+ * @version 2
+ */
+const inmemory = () => connect(':memory:');
+// // // // // // // // // // // // // // // // // // // // // // // //
+//                              EXPORTS                              //
+// // // // // // // // // // // // // // // // // // // // // // // //
+export { connect, inmemory, };

package/dist/esm/console-logger.js

@@ -0,0 +1,132 @@
+import { inspect } from 'node:util';
+import {} from './index';
+/**
+ * @private Non-exhaustive table of ASCII codes for styled console
+ *          output.
+ * @since   0.1.21
+ * @version 1
+ */
+const ASCII_STYLE_CODES = {
+    blue: { open: 34, close: 39 },
+    bold: { open: 1, close: 22 },
+    brightRed: { open: 91, close: 39 },
+    dim: { open: 2, close: 22 },
+    green: { open: 32, close: 39 },
+    italic: { open: 3, close: 23 },
+    red: { open: 31, close: 39 },
+    yellow: { open: 33, close: 39 },
+};
+/**
+ * @private A registry of style functions for console output, one for
+ *          each style in the ASCII codes table.
+ * @since   0.1.21
+ * @version 1
+ */
+const s = Object.fromEntries(Object
+    .entries(ASCII_STYLE_CODES)
+    .map(([key, style]) => [key, (str) => `\u001b[${style.open}m${str.toString()}\u001b[${style.close}m`])
+    .concat([['default', (str) => str.toString()]]));
+/**
+ * @private Split the given query into a tuple, where the first elment
+ *          is the statement name (e.g. SELECT, INSERT, etc) and the
+ *          second element is the rest of the query.
+ * @since   0.1.21
+ * @version 1
+ */
+const splitAtStatementName = (str) => [str.split(' ')[0], str.slice(str.indexOf(' '))];
+/**
+ * @private Paints the given SQL depending on what it does (e.g.
+ *          DELETEs are red, SELECTs are green, etc).
+ * @since   0.1.21
+ * @version 1
+ */
+const dye = (sql) => {
+    const [statement, rest] = splitAtStatementName(sql);
+    if (statement === 'INSERT')
+        return s.green(`${s.bold(statement)} ${rest}`);
+    if (statement === 'SELECT')
+        return s.blue(`${s.bold(statement)} ${rest}`);
+    if (statement === 'UPDATE')
+        return s.yellow(`${s.bold(statement)} ${rest}`);
+    if (statement === 'DELETE')
+        return s.brightRed(`${s.bold(statement)} ${rest}`);
+    return sql;
+};
+/**
+ * @private Renders a query parameter value for logging purposes.
+ * @since   0.1.21
+ * @version 1
+ */
+const render = (value) => {
+    if (value === null)
+        return s.dim('null');
+    if (value === undefined)
+        return s.dim('null');
+    if (typeof value === 'boolean')
+        return value.toString();
+    if (typeof value === 'number')
+        return s.blue(value.toString());
+    if (typeof value === 'string')
+        return [s.dim('`'), value, s.dim('`')].join('');
+    if (value instanceof Date)
+        return s.blue(`${value.toISOString()}`);
+    if (Array.isArray(value))
+        return [s.dim('['), value.map(render).join(s.dim(', ')), s.dim(']')].join('');
+    throw new Error(`Unable to render value: ${inspect(value, true, null, true)}`);
+};
+/**
+ * @private A function that [p]retty-[p]rints the given SQL query, its
+ *          parameters and its error.
+ * @since   0.1.21
+ * @version 1
+ */
+const pp = (sql, params, error) => [
+    dye(sql),
+    ' ',
+    render(params),
+    error
+        ? ('\n\n' + s.red(`${s.bold(error.constructor.name)} ${error.message}\n${error.stack}`.trim()) + '\n\n')
+        : '',
+].join('');
+/**
+ * @private A function that prints the given SQL query, its parameters
+ *          and its error as [p]lain [t]ext (no ASCII styling).
+ * @since   0.1.21
+ * @version 1
+ */
+const pt = (sql, params, error) => [
+    sql,
+    ' ',
+    render(params),
+    error
+        ? ('\n\n' + (`${error.constructor.name} ${error.message}\n${error.stack}`.trim()) + '\n\n')
+        : '',
+].join('');
+/**
+ * @private Returns a function that pretty-prints its given arguments
+ *          to the specified stream.
+ * @since   0.1.21
+ * @version 1
+ */
+const handler = (stream, fn) => (...args) => { stream.write(fn(...args)); };
+/**
+ * @public  Creates a basic console logger that pretty-prints queries.
+ *
+ *          Pretty printing is enabled by default but you can disable
+ *          it to print plain-text instead (no ASCII styling), just
+ *          set the option `pretty` to `false`.
+ * @since   0.1.0
+ * @version 3
+ *
+ * @example
+ * ```ts
+ * import { createConsoleLogger } from '@rwillians/qx/console-logger';
+ *
+ * const prettyLogger = createConsoleLogger();
+ * const plainLogger = createConsoleLogger({ pretty: false });
+ * ```
+ */
+export const createConsoleLogger = (opts = { pretty: true }) => ({
+    debug: handler(process.stdout, opts.pretty ? pp : pt),
+    error: handler(process.stderr, opts.pretty ? pp : pt),
+});