orchid-orm 1.17.14 → 1.17.16

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { columnTypes, QueryHooks, getColumnTypes, getQueryAs, setQueryObjectValue, pushQueryOn, VirtualColumn, pushQueryValue, isQueryReturnsAll, toSQLCacheKey, OrchidOrmInternalError, NotFoundError, Adapter, Db, anyShape, getClonedQueryData } from 'pqb';
+import { columnTypes, QueryHooks, getColumnTypes, getQueryAs, setQueryObjectValue, pushQueryOn, VirtualColumn, pushQueryValue, isQueryReturnsAll, toSQLCacheKey, OrchidOrmInternalError, NotFoundError, Adapter, Db, anyShape, addComputedColumns, getClonedQueryData } from 'pqb';
 export { OrchidOrmError, OrchidOrmInternalError, columnTypes, raw, testTransaction } from 'pqb';
 import { getStackTrace, applyMixins, getCallerFilePath, snakeCaseKey, toSnakeCase, emptyArray, toArray } from 'orchid-core';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -24,7 +24,7 @@ const createBaseTable = ({
   const base = (_a = class {
     constructor() {
       this.snakeCase = snakeCase;
-      this.columnTypes = columnTypes$1;
+      this.types = columnTypes$1;
       this.q = {};
       this.language = language;
     }
@@ -72,6 +72,99 @@ const createBaseTable = ({
       }
       return this.constructor.prototype.columns = shape;
     }
+    /**
+     * You can add a generated column in the migration (see [generated](/guide/migration-column-methods.html#generated-column)),
+     * such column will persist in the database, it can be indexed.
+     *
+     * Or you can add a computed column on the ORM level, without adding it to the database, in such a way:
+     *
+     * ```ts
+     * import { BaseTable } from './baseTable';
+     *
+     * export class UserTable extends BaseTable {
+     *   readonly table = 'user';
+     *   columns = this.setColumns((t) => ({
+     *     id: t.identity().primaryKey(),
+     *     firstName: t.string(),
+     *     lastName: t.string(),
+     *   }));
+     *
+     *   computed = this.setComputed({
+     *     fullName: (q) =>
+     *       q.sql`${q.column('firstName')} || ' ' || ${q.column('lastName')}`.type(
+     *         (t) => t.string(),
+     *       ),
+     *   });
+     * }
+     * ```
+     *
+     * `setComputed` takes an object where keys are computed column names, and values are functions returning raw SQL.
+     *
+     * Use `q.column` as shown above to reference a table column, it will be prefixed with a correct table name even if the table is joined under a different name.
+     *
+     * Computed columns are not selected by default, only on demand:
+     *
+     * ```ts
+     * const a = await db.user.take();
+     * a.fullName; // not selected
+     *
+     * const b = await db.user.select('*', 'fullName');
+     * b.fullName; // selected
+     *
+     * // Table post belongs to user as an author.
+     * // it's possible to select joined computed column:
+     * const posts = await db.post
+     *   .join('author')
+     *   .select('post.title', 'author.fullName');
+     * ```
+     *
+     * SQL query can be generated dynamically based on the current request context.
+     *
+     * Imagine we are using [AsyncLocalStorage](https://nodejs.org/api/async_context.html#asynchronous-context-tracking)
+     * to keep track of current user's language.
+     *
+     * And we have articles translated to different languages, each article has `title_en`, `title_uk`, `title_be` and so on.
+     *
+     * We can define a computed `title` by passing a function into `sql` method:
+     *
+     * ```ts
+     * type Locale = 'en' | 'uk' | 'be';
+     * const asyncLanguageStorage = new AsyncLocalStorage<Locale>();
+     * const defaultLocale: Locale = 'en';
+     *
+     * export class ArticleTable extends BaseTable {
+     *   readonly table = 'article';
+     *   columns = this.setColumns((t) => ({
+     *     id: t.identity().primaryKey(),
+     *     title_en: t.text(),
+     *     title_uk: t.text().nullable(),
+     *     title_be: t.text().nullable(),
+     *   }));
+     *
+     *   computed = this.setComputed({
+     *     title: (q) =>
+     *       q
+     *         // .sql can take a function that accepts `sql` argument and must return SQL
+     *         .sql((sql) => {
+     *           // get locale dynamically based on current storage value
+     *           const locale = asyncLanguageStorage.getStore() || defaultLocale;
+     *
+     *           // use COALESCE in case when localized title is NULL, use title_en
+     *           return sql`COALESCE(
+     *             ${q.column(`title_${locale}`)},
+     *             ${q.column(`title_${defaultLocale}`)}
+     *           )`;
+     *         })
+     *         .type((t) => t.text()),
+     *   });
+     * }
+     * ```
+     *
+     * @param computed - object where keys are column names and values are functions returning raw SQL
+     */
+    setComputed(computed) {
+      return computed;
+    }
     belongsTo(fn, options) {
       return {
         type: "belongsTo",
@@ -102,7 +195,7 @@ const createBaseTable = ({
     }
   }, _a.nowSQL = nowSQL, _a.exportAs = exportAs, _a.schema = schemaProvider, _a);
   applyMixins(base, [QueryHooks]);
-  base.prototype.columnTypes = columnTypes$1;
+  base.prototype.types = columnTypes$1;
   return base;
 };
 
@@ -1704,7 +1797,7 @@ const orchidORM = (_a, tables) => {
       qb,
       table.table,
       table.columns,
-      table.columnTypes,
+      table.types,
       transactionStorage,
       options2
     );
@@ -1712,6 +1805,12 @@ const orchidORM = (_a, tables) => {
     dbTable.db = result;
     dbTable.filePath = table.filePath;
     dbTable.name = table.constructor.name;
+    if (table.computed) {
+      addComputedColumns(
+        dbTable,
+        table.computed
+      );
+    }
     result[key] = dbTable;
   }
   applyRelations(qb, tableInstances, result);