@rwillians/qx 0.1.11 → 0.1.13

package/README.md

@@ -1,7 +1,7 @@
-# qx (provisory name)
+# qx
 
-A teeny tiny ORM for TypeScript and JavaScript inspired by Elixir's
-[Ecto](https://hexdocs.pm/ecto).
+A teeny tiny, type-safe and dependency-free ORM for TypeScript and
+JavaScript.
 
 Built for you who wants a simple, small ORM that just works.
 
@@ -10,10 +10,10 @@ import * as sqlite from '@rwillians/qx/bun-sqlite';
 import { create, from, into, table } from '@rwillians/qx';
 
 const users = table('users', t => ({
-  id: t.integer({ primaryKey: true, autogenerate: true }),
+  id: t.integer().autoincrement().primaryKey(),
   name: t.string(),
   email: t.string(),
-  createdAt: t.timestamp({ autogenerate: true }),
+  createdAt: t.datetime(),
 }));
 
 // ...

package/dist/cjs/bun-sqlite.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.connect = void 0;
+exports.inmemory = exports.connect = void 0;
 const bun_sqlite_1 = require("bun:sqlite");
 const node_util_1 = require("node:util");
 const u = require("./utils");
@@ -505,3 +505,10 @@ class BunSQLite {
  */
 const connect = (...args) => new BunSQLite(new bun_sqlite_1.Database(...args));
 exports.connect = connect;
+/**
+ * @public  An in-memory database connection.
+ * @since   0.1.12
+ * @version 1
+ */
+const inmemory = connect(':memory:');
+exports.inmemory = inmemory;

package/dist/cjs/console-logger.js

@@ -5,11 +5,12 @@ const node_util_1 = require("node:util");
 /**
  * @public  Creates a basic console logger that logs all queries.
  * @since   0.1.0
- * @version 1
+ * @version 2
  */
 const createConsoleLogger = () => ({
     query: {
         debug: (sql, params) => { process.stdout.write(sql + ' ' + (0, node_util_1.inspect)(params, false, null, true) + '\n'); },
+        error: (sql, params) => { process.stderr.write(sql + ' ' + (0, node_util_1.inspect)(params, false, null, true) + '\n'); },
     },
 });
 exports.createConsoleLogger = createConsoleLogger;

package/dist/cjs/experimental-migration.js

@@ -14,15 +14,16 @@ const migrations = (0, index_1.table)('schema_migrations', t => ({
  */
 const defineMigrations = (migs) => async (db) => {
     await index_1.create.table(migrations, { ifNotExists: true }).onto(db);
+    const { mostRecentId } = await (0, index_1.from)(migrations.as('m'))
+        .orderBy(({ m }) => [[m.timestamp, 'DESC']])
+        .select(({ m }) => ({ mostRecentId: m.id }))
+        .one(db) || { mostRecentId: '' };
     for (const [id, migrate] of Object.entries(migs)) {
-        const alreadyMigrated = await (0, index_1.from)(migrations.as('m'))
-            .where(({ m }) => index_1.expr.eq(m.id, id))
-            .exists(db);
-        if (alreadyMigrated)
+        if (id < mostRecentId)
             continue;
         await (0, index_1.transaction)(db, async () => {
             await migrate(db);
-            await (0, index_1.into)(migrations).insert({ id, timestamp: new Date() }).run(db);
+            await (0, index_1.into)(migrations).values({ id, timestamp: new Date() }).insert(db);
         });
     }
 };

package/dist/cjs/index.js

@@ -21,7 +21,7 @@ const TABLE_ALIAS = Symbol.for('~exto.table-alias');
 /**
  * @private A builder for column properties.
  * @since   0.1.0
- * @version 1
+ * @version 2
  */
 class ColumnPropsBuilder {
     props;
@@ -39,9 +39,12 @@ class ColumnPropsBuilder {
         return new ColumnPropsBuilder({ ...this.props, autoincrement: true });
     }
     /**
-     * @public  Sets a default value for the column.
+     * @public  Sets a default value for the column. This is not the
+     *          table's default value for the column, but rather a
+     *          fallback value that qx will use when inserting a new row
+     *          where this column is nullish.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      */
     default(value) {
         return new ColumnPropsBuilder({ ...this.props, default: value });
@@ -49,12 +52,12 @@ class ColumnPropsBuilder {
     /**
      * @public  Marks the column as nullable.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      * @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');
+            throw new Error('Cannot make a primary key column nullable');
         const { schema, ...props } = this.props;
         return new ColumnPropsBuilder({ ...props, nullable: true, schema: std.nullable(schema) });
     }
@@ -72,9 +75,11 @@ class ColumnPropsBuilder {
     /**
      * @public  Marks the column as unique.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      */
     unique() {
+        if (this.props.primaryKey)
+            throw new Error('Primary key columns are already unique');
         return new ColumnPropsBuilder({ ...this.props, unique: true });
     }
 }
@@ -285,6 +290,21 @@ const expr = {
      * @version 1
      */
     not: (expr) => ({ not: expr }),
+    // // // // // // // // // // // // // // // // // // // // // // //
+    //                         SEMANTICS ONLY                         //
+    // // // // // // // // // // // // // // // // // // // // // // //
+    /**
+     * @public  Builds an ascending order expression.
+     * @since   0.1.13
+     * @version 1
+     */
+    asc: (expr) => [expr, 'ASC'],
+    /**
+     * @public  Builds a descending order expression.
+     * @since   0.1.13
+     * @version 1
+     */
+    desc: (expr) => [expr, 'DESC'],
 };
 exports.expr = expr;
 /**
@@ -538,9 +558,9 @@ class InsertBuilder {
     /**
      * @public  Adds one or more rows to be inserted.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      */
-    insert(rows) {
+    values(rows) {
         this.rows.push(...(u.wrap(rows)));
         return this;
     }
@@ -549,7 +569,7 @@ class InsertBuilder {
      * @since   0.1.0
      * @version 1
      */
-    async run(db) {
+    async insert(db) {
         if (this.rows.length === 0)
             return [];
         const insertShape = getInsertShape(this.table);

package/dist/esm/bun-sqlite.js

@@ -501,7 +501,13 @@ class BunSQLite {
  * @version 1
  */
 const connect = (...args) => new BunSQLite(new Database(...args));
+/**
+ * @public  An in-memory database connection.
+ * @since   0.1.12
+ * @version 1
+ */
+const inmemory = connect(':memory:');
 // // // // // // // // // // // // // // // // // // // // // // // //
 //                              EXPORTS                              //
 // // // // // // // // // // // // // // // // // // // // // // // //
-export { connect, };
+export { connect, inmemory, };

package/dist/esm/console-logger.js

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

package/dist/esm/experimental-migration.js

@@ -11,15 +11,16 @@ const migrations = table('schema_migrations', t => ({
  */
 export const defineMigrations = (migs) => async (db) => {
     await create.table(migrations, { ifNotExists: true }).onto(db);
+    const { mostRecentId } = await from(migrations.as('m'))
+        .orderBy(({ m }) => [[m.timestamp, 'DESC']])
+        .select(({ m }) => ({ mostRecentId: m.id }))
+        .one(db) || { mostRecentId: '' };
     for (const [id, migrate] of Object.entries(migs)) {
-        const alreadyMigrated = await from(migrations.as('m'))
-            .where(({ m }) => expr.eq(m.id, id))
-            .exists(db);
-        if (alreadyMigrated)
+        if (id < mostRecentId)
             continue;
         await transaction(db, async () => {
             await migrate(db);
-            await into(migrations).insert({ id, timestamp: new Date() }).run(db);
+            await into(migrations).values({ id, timestamp: new Date() }).insert(db);
         });
     }
 };

package/dist/esm/index.js

@@ -18,7 +18,7 @@ const TABLE_ALIAS = Symbol.for('~exto.table-alias');
 /**
  * @private A builder for column properties.
  * @since   0.1.0
- * @version 1
+ * @version 2
  */
 class ColumnPropsBuilder {
     props;
@@ -36,9 +36,12 @@ class ColumnPropsBuilder {
         return new ColumnPropsBuilder({ ...this.props, autoincrement: true });
     }
     /**
-     * @public  Sets a default value for the column.
+     * @public  Sets a default value for the column. This is not the
+     *          table's default value for the column, but rather a
+     *          fallback value that qx will use when inserting a new row
+     *          where this column is nullish.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      */
     default(value) {
         return new ColumnPropsBuilder({ ...this.props, default: value });
@@ -46,12 +49,12 @@ class ColumnPropsBuilder {
     /**
      * @public  Marks the column as nullable.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      * @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');
+            throw new Error('Cannot make a primary key column nullable');
         const { schema, ...props } = this.props;
         return new ColumnPropsBuilder({ ...props, nullable: true, schema: std.nullable(schema) });
     }
@@ -69,9 +72,11 @@ class ColumnPropsBuilder {
     /**
      * @public  Marks the column as unique.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      */
     unique() {
+        if (this.props.primaryKey)
+            throw new Error('Primary key columns are already unique');
         return new ColumnPropsBuilder({ ...this.props, unique: true });
     }
 }
@@ -280,6 +285,21 @@ const expr = {
      * @version 1
      */
     not: (expr) => ({ not: expr }),
+    // // // // // // // // // // // // // // // // // // // // // // //
+    //                         SEMANTICS ONLY                         //
+    // // // // // // // // // // // // // // // // // // // // // // //
+    /**
+     * @public  Builds an ascending order expression.
+     * @since   0.1.13
+     * @version 1
+     */
+    asc: (expr) => [expr, 'ASC'],
+    /**
+     * @public  Builds a descending order expression.
+     * @since   0.1.13
+     * @version 1
+     */
+    desc: (expr) => [expr, 'DESC'],
 };
 /**
  * @public  Expression type guards.
@@ -529,9 +549,9 @@ class InsertBuilder {
     /**
      * @public  Adds one or more rows to be inserted.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      */
-    insert(rows) {
+    values(rows) {
         this.rows.push(...(u.wrap(rows)));
         return this;
     }
@@ -540,7 +560,7 @@ class InsertBuilder {
      * @since   0.1.0
      * @version 1
      */
-    async run(db) {
+    async insert(db) {
         if (this.rows.length === 0)
             return [];
         const insertShape = getInsertShape(this.table);

package/dist/types/bun-sqlite.d.ts

@@ -50,4 +50,10 @@ declare class BunSQLite implements IDatabase {
  * @version 1
  */
 declare const connect: (...args: ConstructorParameters<typeof Database>) => BunSQLite;
-export { connect, };
+/**
+ * @public  An in-memory database connection.
+ * @since   0.1.12
+ * @version 1
+ */
+declare const inmemory: BunSQLite;
+export { connect, inmemory, };

package/dist/types/console-logger.d.ts

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

package/dist/types/index.d.ts

@@ -40,10 +40,9 @@ type ColumnProps<T extends std.Schema = std.Schema> = {
      */
     autoincrement?: true;
     /**
-     * @public  The default value for the column or a function that
-     *          returns it. If a column has no value (nullish) and
-     *          default function was provided, then it will be called
-     *          once for each row right before its insertion.
+     * @public  The default value for the column. If a column has
+     *          nullish value in an insert, then this value will be used
+     *          instead.
      * @since   0.1.0
      * @version 1
      */
@@ -92,7 +91,7 @@ type ColumnProps<T extends std.Schema = std.Schema> = {
 /**
  * @public  A column definition.
  * @since   0.1.0
- * @version 1
+ * @version 2
  */
 type Column<S extends string = string, T extends ColumnProps = ColumnProps> = Expand<T & {
     /**
@@ -111,15 +110,15 @@ type Column<S extends string = string, T extends ColumnProps = ColumnProps> = Ex
     /**
      * @public  The column's input type, cached.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      */
-    inputType: std.input<T['schema']>;
+    inferInput: std.input<T['schema']>;
     /**
      * @public  The column's output type, cached.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      */
-    outputType: std.output<T['schema']>;
+    inferOutput: std.output<T['schema']>;
 }>;
 /**
  * @public  A table definition.
@@ -208,28 +207,28 @@ type OmitOnUpdate = {
 /**
  * @private Infers the output type of a table's row.
  * @since   0.1.0
- * @version 1
+ * @version 2
  */
 type Infer<T extends Table> = {
-    [K in keyof T['columns']]: T['columns'][K]['outputType'];
+    [K in keyof T['columns']]: T['columns'][K]['inferOutput'];
 };
 /**
  * @private Infers the input type required to insert a new row.
  * @since   0.1.0
- * @version 1
+ * @version 2
  */
 type InferForInsert<T extends Table> = Expand<{
-    [K in keyof T['columns'] as T['columns'][K] extends OmitOnInsert | OptionalOnInsert ? never : K]: T['columns'][K]['inputType'];
+    [K in keyof T['columns'] as T['columns'][K] extends OmitOnInsert | OptionalOnInsert ? never : K]: T['columns'][K]['inferInput'];
 } & {
-    [K in keyof T['columns'] as T['columns'][K] extends OptionalOnInsert ? K : never]?: T['columns'][K]['inputType'];
+    [K in keyof T['columns'] as T['columns'][K] extends OptionalOnInsert ? K : never]?: T['columns'][K]['inferInput'];
 }>;
 /**
  * @private Infers the input type required to update an existing row.
  * @since   0.1.0
- * @version 1
+ * @version 2
  */
 type InferForUpdate<T extends Table> = {
-    [K in keyof T['columns'] as T['columns'][K] extends OmitOnUpdate ? never : K]?: T['columns'][K]['inputType'];
+    [K in keyof T['columns'] as T['columns'][K] extends OmitOnUpdate ? never : K]?: T['columns'][K]['inferInput'];
 };
 /**
  * @private Adds the ability to infer types of a table.
@@ -259,7 +258,7 @@ type Inferrable<T extends Table> = T & {
 /**
  * @private A builder for column properties.
  * @since   0.1.0
- * @version 1
+ * @version 2
  */
 declare class ColumnPropsBuilder<T extends ColumnProps = ColumnProps> {
     readonly props: T;
@@ -273,17 +272,20 @@ declare class ColumnPropsBuilder<T extends ColumnProps = ColumnProps> {
         autoincrement: true;
     }>>;
     /**
-     * @public  Sets a default value for the column.
+     * @public  Sets a default value for the column. This is not the
+     *          table's default value for the column, but rather a
+     *          fallback value that qx will use when inserting a new row
+     *          where this column is nullish.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      */
-    default<S extends std.output<T['schema']>, U extends S | (() => S)>(value: U): ColumnPropsBuilder<Expand<T & {
-        default: U;
+    default<S extends std.output<T['schema']> | (() => std.output<T['schema']>)>(value: S): ColumnPropsBuilder<Expand<T & {
+        default: S;
     }>>;
     /**
      * @public  Marks the column as nullable.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      * @throws {Error} if the column is a primary key.
      */
     nullable(): ColumnPropsBuilder<Expand<Omit<T, "schema"> & {
@@ -302,7 +304,7 @@ declare class ColumnPropsBuilder<T extends ColumnProps = ColumnProps> {
     /**
      * @public  Marks the column as unique.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      */
     unique(): ColumnPropsBuilder<Expand<T & {
         unique: true;
@@ -648,6 +650,18 @@ declare const expr: {
      * @version 1
      */
     not: <E extends Expr>(expr: E) => ExprNot;
+    /**
+     * @public  Builds an ascending order expression.
+     * @since   0.1.13
+     * @version 1
+     */
+    asc: (expr: Expr) => readonly [Expr, "ASC"];
+    /**
+     * @public  Builds a descending order expression.
+     * @since   0.1.13
+     * @version 1
+     */
+    desc: (expr: Expr) => readonly [Expr, "DESC"];
 };
 /**
  * @public  Expression type guards.
@@ -982,6 +996,12 @@ interface ILogger {
          * @version 1
          */
         debug(sql: string, params: any[]): void;
+        /**
+         * @public  Logs a query that has failed with an error.
+         * @since   0.1.12
+         * @version 1
+         */
+        error(sql: string, params: any[], error: Error): void;
     };
 }
 /**
@@ -1064,15 +1084,15 @@ declare class InsertBuilder<T extends Table> {
     /**
      * @public  Adds one or more rows to be inserted.
      * @since   0.1.0
-     * @version 1
+     * @version 2
      */
-    insert(rows: InferForInsert<T> | InferForInsert<T>[]): this;
+    values(rows: InferForInsert<T> | InferForInsert<T>[]): this;
     /**
      * @public  Executes the insert statement onto the given database.
      * @since   0.1.0
      * @version 1
      */
-    run(db: IDatabase): Promise<Expand<Infer<T>>[]>;
+    insert(db: IDatabase): Promise<Expand<Infer<T>>[]>;
 }
 /**
  * @public  Starts an insert statement for the given table.
@@ -1150,10 +1170,10 @@ type Query<T extends Record<string, Aliased<string, Table>> = Record<string, Ali
 /**
  * @private Infers the selection output type of given query.
  * @since   0.1.0
- * @version 1
+ * @version 2
  */
 type InferSelection<T extends Query> = {
-    [K in keyof T['select'] & string]: T['select'][K]['outputType'];
+    [K in keyof T['select'] & string]: T['select'][K]['inferOutput'];
 };
 /**
  * @public  Select statement builder with a fluent API.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rwillians/qx",
   "description": "A teeny tiny ORM for SQLite.",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "author": "Rafael Willians <me@rwillians.com>",
   "license": "MIT",
   "repository": {