@rvoh/dream 0.29.1

package/dist/esm/src/db/migration-helpers/DreamMigrationHelpers.js

@@ -0,0 +1,190 @@
+import { sql } from 'kysely';
+export default class DreamMigrationHelpers {
+    /**
+     * Unique indexes cannot be populated by the same value even within a transaction,
+     * but deferrable unique constraints can.
+     *
+     * The Sortable decorator requires deferrable unique constraints rather than unique
+     * indexes.
+     *
+     * @param db - The Kysely database object passed into the migration up/down function
+     * @param constraintName - The name of the constraint to create
+     * @param opts.table - The name of the table
+     * @param opts.columns[] - The names of the columns to include in the constraint
+     *
+     */
+    static async addDeferrableUniqueConstraint(db, constraintName, { table, columns, }) {
+        await this.dropConstraint(db, constraintName, { table });
+        await sql `
+    ALTER TABLE ${sql.table(table)}
+    ADD CONSTRAINT ${sql.table(constraintName)}
+      UNIQUE (${sql.raw(columns.join(', '))})
+      DEFERRABLE INITIALLY DEFERRED;
+  `.execute(db);
+    }
+    /**
+     * Add a value to an enum.
+     *
+     * Note that this always includes "IF NOT EXISTS", so is safe to re-run multiple times.
+     *
+     * @param db - The Kysely database object passed into the migration up/down function
+     * @param opt.enumName - The name of the enum to modify
+     * @param opt.value - The name of the value to add to the enum
+     *
+     */
+    static async addEnumValue(db, { enumName, value }) {
+        await sql `ALTER TYPE ${sql.raw(enumName)} ADD VALUE IF NOT EXISTS '${sql.raw(value)}';`.execute(db);
+    }
+    /**
+     * Create a database extension.
+     *
+     * ```
+     *   // Add the case insensitive extension
+     *   await DreamMigrationHelpers.createExtension(db, 'citext')
+     *
+     *   // Add the pg trigram extension
+     *   await DreamMigrationHelpers.createExtension(db, 'pg_trgm')
+     * ```
+     *
+     * @param db - The Kysely database object passed into the migration up/down function
+     * @param extensionName - The name of the database extension to add
+     * @param opt.ifNotExists - Only add the extension if it doesn't already exist
+     * @param opt.publicSchema - Create using the public schema
+     *
+     */
+    static async createExtension(db, extensionName, { ifNotExists = true, publicSchema = true } = {}) {
+        const ifNotExistsText = ifNotExists ? ' IF NOT EXISTS ' : ' ';
+        const publicSchemaText = publicSchema ? ' WITH SCHEMA public' : '';
+        await sql `
+    CREATE EXTENSION${sql.raw(ifNotExistsText)}"${sql.raw(extensionName)}"${sql.raw(publicSchemaText)};
+  `.execute(db);
+    }
+    /**
+     * Create a gin index
+     *
+     * @param db - The Kysely database object passed into the migration up/down function
+     * @param indexName - The name of the constraint to create
+     * @param opts.table - The name of the table
+     * @param opts.column - The name of the column to index
+     *
+     */
+    static async createGinIndex(db, indexName, { table, column }) {
+        await sql `
+    CREATE INDEX IF NOT EXISTS ${sql.raw(indexName)} ON ${sql.raw(table)} USING GIN (${sql.raw(`${column} gin_trgm_ops`)});
+  `.execute(db);
+    }
+    /**
+     * Drop a constraint
+     *
+     * Note that this always includes "IF NOT EXISTS", so is safe to re-run multiple times.
+     *
+     * @param db - The Kysely database object passed into the migration up/down function
+     * @param constraintName - The name of the constraint to create
+     * @param opts.table - The name of the table
+     *
+     */
+    static async dropConstraint(db, constraintName, { table }) {
+        await sql `
+    ALTER TABLE ${sql.table(table)} DROP CONSTRAINT IF EXISTS ${sql.table(constraintName)};
+  `.execute(db);
+    }
+    /**
+     * Drop a value from an enum and replace it (or optionally remove it from array columns)
+     *
+     * @param db - The Kysely database object passed into the migration up/down function
+     * @param opt.enumName - The name of the enum to modify
+     * @param opt.value - The name of the value to drop from the enum
+     * @param opt.replacements[] - Details about which table and column to change and which value to replace the dropped value with (or remove it if the column is an array)
+     *
+     */
+    static async dropEnumValue(db, { enumName, value, replacements }) {
+        // temporarily set all table columns depending on this enum to an acceptable alternate type
+        for (const tableAndColumnToChange of replacements) {
+            const tableAndColumnToChangeAsArray = tableAndColumnToChange;
+            const isArray = tableAndColumnToChangeAsArray.array || false;
+            await db.schema
+                .alterTable(tableAndColumnToChange.table)
+                .alterColumn(tableAndColumnToChange.column, col => col.setDataType(computedTemporaryType(isArray)))
+                .execute();
+        }
+        // collect enum values before dropping type
+        const allEnumValues = await getEnumValues(db, enumName);
+        // drop type and re-create it without the enum value
+        // we are trying to drop
+        await db.schema.dropType(enumName).execute();
+        await db.schema
+            .createType(enumName)
+            .asEnum(allEnumValues.filter(val => val !== value))
+            .execute();
+        for (const tableAndColumnToChange of replacements) {
+            const isArray = tableAndColumnToChange.array || false;
+            if (isArray) {
+                await replaceArrayValues(db, value, tableAndColumnToChange);
+                await updateTableColumnToNewEnumArrayType(db, enumName, tableAndColumnToChange);
+            }
+            else {
+                await replaceNonArrayValues(db, value, tableAndColumnToChange);
+                await updateTableColumnToNewEnumType(db, enumName, tableAndColumnToChange);
+            }
+        }
+    }
+}
+async function getEnumValues(db, enumName) {
+    const response = await sql `SELECT unnest(enum_range(NULL::${sql.raw(enumName)}))`.execute(db);
+    return response.rows.map(row => row.unnest);
+}
+// finds any records in the specified table
+// who's targeted column is an array containing
+// the enum value we are trying to drop,
+// and updates their values to a safe value
+// provided by the user
+async function replaceArrayValues(db, value, tableAndColumnToChange) {
+    const { column, table } = tableAndColumnToChange;
+    await db
+        .updateTable(table)
+        .set({
+        [column]: tableAndColumnToChange.behavior === 'remove'
+            ? sql.raw(`array_remove(${column}, '${value}')`)
+            : sql.raw(`array_replace(${column}, '${value}', '${tableAndColumnToChange.replaceWith}')`),
+    })
+        .where(sql.raw(`'${value}'`), '=', sql.raw(`ANY(${column})`))
+        .execute();
+}
+// finds any records in the specified table
+// who's targeted column is  the enum value
+// we are trying to drop, and updates their
+// values to a safe value provided by
+// the user
+async function replaceNonArrayValues(db, value, tableAndColumnToChange) {
+    const { table, column, replaceWith } = tableAndColumnToChange;
+    await db
+        .updateTable(table)
+        .set({ [column]: replaceWith })
+        .where(column, '=', value)
+        .execute();
+}
+// updates the table's targeted column to the newly-created enum array
+async function updateTableColumnToNewEnumArrayType(db, enumName, tableAndColumnToChange) {
+    const { table, column } = tableAndColumnToChange;
+    await sql `
+    ALTER TABLE ${sql.raw(table)}
+    ALTER ${sql.raw(column)}
+    TYPE ${sql.raw(enumName)}[]
+    USING ${sql.raw(column)}::${sql.raw(enumName)}[];
+  `.execute(db);
+}
+// updates the table's targeted column to the newly-created enum
+async function updateTableColumnToNewEnumType(db, enumName, tableAndColumnToChange) {
+    const { table, column } = tableAndColumnToChange;
+    await sql `
+    ALTER TABLE ${sql.raw(table)}
+    ALTER ${sql.raw(column)}
+    TYPE ${sql.raw(enumName)}
+    USING ${sql.raw(column)}::${sql.raw(enumName)};
+  `.execute(db);
+}
+function computedTemporaryType(array) {
+    if (array)
+        return sql `text[]`;
+    return 'text';
+}

package/dist/esm/src/db/reflections.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/src/db/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/src/db/validators/validateColumn.js

@@ -0,0 +1,8 @@
+import InvalidColumnName from '../../errors/InvalidColumnName.js';
+export default function validateColumn(schema, tableName, columnName) {
+    if (!Object.prototype.hasOwnProperty.call(schema, tableName))
+        throw new InvalidColumnName(tableName, columnName);
+    if (!Object.prototype.hasOwnProperty.call(schema[tableName]?.columns, columnName))
+        throw new InvalidColumnName(tableName, columnName);
+    return columnName;
+}

package/dist/esm/src/db/validators/validateTable.js

@@ -0,0 +1,6 @@
+import InvalidTableName from '../../errors/InvalidTableName.js';
+export default function validateTable(schema, tableName) {
+    if (!Object.prototype.hasOwnProperty.call(schema, tableName))
+        throw new InvalidTableName(schema, tableName);
+    return tableName;
+}

package/dist/esm/src/db/validators/validateTableAlias.js

@@ -0,0 +1,52 @@
+import InvalidTableAlias from '../../errors/InvalidTableAlias.js';
+export default function validateTableAlias(tableAlias) {
+    if (!/^[a-zA-Z0-9_]*$/.test(tableAlias) || SINGLE_WORD_SQL_KEYWORDS.includes(tableAlias.toUpperCase()))
+        throw new InvalidTableAlias(tableAlias);
+    return tableAlias;
+}
+const SINGLE_WORD_SQL_KEYWORDS = [
+    'ADD',
+    'ALL',
+    'ALTER',
+    'AND',
+    'ANY',
+    'AS',
+    'ASC',
+    'BACKUP',
+    'BETWEEN',
+    'CASE',
+    'CHECK',
+    'COLUMN',
+    'CONSTRAINT',
+    'CREATE',
+    'DATABASE',
+    'DEFAULT',
+    'DELETE',
+    'DESC',
+    'DISTINCT',
+    'DROP',
+    'EXEC',
+    'EXISTS',
+    'FROM',
+    'HAVING',
+    'IN',
+    'INDEX',
+    'JOIN',
+    'LIKE',
+    'LIMIT',
+    'NOT',
+    'OR',
+    'PROCEDURE',
+    'ROWNUM',
+    'SELECT',
+    'SET',
+    'TABLE',
+    'TOP',
+    'TRUNCATE',
+    'UNION',
+    'UNIQUE',
+    'UPDATE',
+    'VALUES',
+    'VIEW',
+    'WHERE',
+];

package/dist/esm/src/decorators/DecoratorContextType.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/src/decorators/Decorators.js

@@ -0,0 +1,323 @@
+import BelongsTo from './associations/BelongsTo.js';
+import HasMany from './associations/HasMany.js';
+import HasOne from './associations/HasOne.js';
+import AfterCreate from './hooks/AfterCreate.js';
+import AfterCreateCommit from './hooks/AfterCreateCommit.js';
+import AfterDestroy from './hooks/AfterDestroy.js';
+import AfterDestroyCommit from './hooks/AfterDestroyCommit.js';
+import AfterSave from './hooks/AfterSave.js';
+import AfterSaveCommit from './hooks/AfterSaveCommit.js';
+import AfterUpdate from './hooks/AfterUpdate.js';
+import AfterUpdateCommit from './hooks/AfterUpdateCommit.js';
+import BeforeCreate from './hooks/BeforeCreate.js';
+import BeforeDestroy from './hooks/BeforeDestroy.js';
+import BeforeSave from './hooks/BeforeSave.js';
+import BeforeUpdate from './hooks/BeforeUpdate.js';
+import Sortable from './sortable/Sortable.js';
+export default class Decorators {
+    /**
+     * Establishes a "BelongsTo" association between the base dream
+     * and the child dream, where the base dream has a foreign key
+     * which points back to the child dream.
+     *
+     * ```ts
+     * class UserSettings extends ApplicationModel {
+     *   @Deco.BelongsTo('User')
+     *   public user: User
+     *   public userId: DreamColumn<UserSettings, 'userId'>
+     * }
+     *
+     * class User extends ApplicationModel {
+     *   @Deco.HasOne('UserSettings')
+     *   public userSettings: UserSettings
+     * }
+     * ```
+     *
+     *
+     *
+     * @param modelCB - a function that immediately returns the dream class you are associating with this dream class
+     * @param options - the options you want to use to apply to this association
+     * @returns A BelongsTo decorator
+     */
+    BelongsTo(globalAssociationNameOrNames, options = {}) {
+        return BelongsTo(globalAssociationNameOrNames, options);
+    }
+    /**
+     *
+     * Establishes a "HasMany" association between the base dream
+     * and the child dream, where the child dream has a foreign key
+     * which points back to the base dream.
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   @Deco.HasMany('Post')
+     *   public posts: Post[]
+     * }
+     *
+     * class Post extends ApplicationModel {
+     *   @Deco.BelongsTo('User')
+     *   public user: User
+     *   public userId: DreamColumn<Post, 'userId'>
+     * }
+     * ```
+     *
+     * @param modelCB - a function that immediately returns the dream class you are associating with this dream class
+     * @param options - the options you want to use to apply to this association
+     * @returns A HasMany decorator
+     */
+    HasMany(globalAssociationNameOrNames, options = {}) {
+        return HasMany(globalAssociationNameOrNames, options);
+    }
+    /**
+     * Establishes a "HasOne" association between the base dream
+     * and the child dream, where the child dream has a foreign key
+     * which points back to the base dream.
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   @Deco.HasOne('UserSettings')
+     *   public userSettings: UserSettings
+     * }
+     *
+     * class UserSettings extends ApplicationModel {
+     *   @Deco.BelongsTo('User')
+     *   public user: User
+     *   public userId: DreamColumn<UserSettings, 'userId'>
+     * }
+     * ```
+     *
+     * @param modelCB - A function that immediately returns the dream class you are associating with this dream class
+     * @param options - The options you want to use to apply to this association
+     * @returns A HasOne decorator
+     */
+    HasOne(globalAssociationNameOrNames, options = {}) {
+        return HasOne(globalAssociationNameOrNames, options);
+    }
+    //////////////
+    // end: HasOne
+    //////////////
+    /**
+     * Shortcut to the Sortable decorator, which also provides extra type protection which cannot be provided
+     * with the Sortable decorator.
+     *
+     * @param scope - The column, association, or combination there-of which you would like to restrict the incrementing logic to
+     * @returns A Sortable decorator
+     */
+    Sortable(opts) {
+        return Sortable(opts);
+    }
+    /**
+     * Shortcut to the BeforeCreate decorator
+     *
+     * ```ts
+     * class User {
+     *   User.BeforeCreate()
+     *   public doSomething() {
+     *     console.log('hi!')
+     *   }
+     * }
+     * ```
+     *
+     * @returns The BeforeCreate decorator
+     *
+     */
+    BeforeCreate(opts) {
+        return BeforeCreate(opts);
+    }
+    /**
+     * Shortcut to the BeforeSave decorator
+     *
+     * ```ts
+     * class User {
+     *   User.BeforeSave()
+     *   public doSomething() {
+     *     console.log('hi!')
+     *   }
+     * }
+     * ```
+     *
+     * @returns The BeforeSave decorator
+     *
+     */
+    BeforeSave(opts) {
+        return BeforeSave(opts);
+    }
+    /**
+     * Shortcut to the BeforeUpdate decorator
+     *
+     * ```ts
+     * class User {
+     *   User.BeforeUpdate()
+     *   public doSomething() {
+     *     console.log('hi!')
+     *   }
+     * }
+     * ```
+     *
+     * @returns The BeforeUpdate decorator
+     *
+     */
+    BeforeUpdate(opts) {
+        return BeforeUpdate(opts);
+    }
+    /**
+     * Shortcut to the BeforeDestroy decorator
+     *
+     * ```ts
+     * class User {
+     *   User.BeforeDestroy()
+     *   public doSomething() {
+     *     console.log('hi!')
+     *   }
+     * }
+     * ```
+     *
+     * @returns The BeforeDestroy decorator
+     */
+    BeforeDestroy() {
+        return BeforeDestroy();
+    }
+    /**
+     * Shortcut to the AfterCreate decorator
+     *
+     * ```ts
+     * class User {
+     *   User.AfterCreate()
+     *   public doSomething() {
+     *     console.log('hi!')
+     *   }
+     * }
+     * ```
+     *
+     * @returns The AfterCreate decorator
+     *
+     */
+    AfterCreate(opts) {
+        return AfterCreate(opts);
+    }
+    /**
+     * Shortcut to the AfterCreateCommit decorator
+     *
+     * ```ts
+     * class User {
+     *   User.AfterCreateCommit()
+     *   public doSomething() {
+     *     console.log('hi!')
+     *   }
+     * }
+     * ```
+     *
+     * @returns The AfterCreateCommit decorator
+     */
+    AfterCreateCommit(opts) {
+        return AfterCreateCommit(opts);
+    }
+    /**
+     * Shortcut to the AfterSave decorator
+     *
+     * ```ts
+     * class User {
+     *   User.AfterSave()
+     *   public doSomething() {
+     *     console.log('hi!')
+     *   }
+     * }
+     * ```
+     *
+     * @returns The AfterSave decorator
+     *
+     */
+    AfterSave(opts) {
+        return AfterSave(opts);
+    }
+    /**
+     * Shortcut to the AfterSaveCommit decorator
+     *
+     * ```ts
+     * class User {
+     *   User.AfterSaveCommit()
+     *   public doSomething() {
+     *     console.log('hi!')
+     *   }
+     * }
+     * ```
+     *
+     * @returns The AfterSaveCommit decorator
+     *
+     */
+    AfterSaveCommit(opts) {
+        return AfterSaveCommit(opts);
+    }
+    /**
+     * Shortcut to the AfterUpdate decorator
+     *
+     * ```ts
+     * class User {
+     *   User.AfterUpdate()
+     *   public doSomething() {
+     *     console.log('hi!')
+     *   }
+     * }
+     * ```
+     *
+     * @returns The AfterUpdate decorator
+     *
+     */
+    AfterUpdate(opts) {
+        return AfterUpdate(opts);
+    }
+    /**
+     * Shortcut to the AfterUpdateCommit decorator
+     *
+     * ```ts
+     * class User {
+     *   User.AfterUpdateCommit()
+     *   public doSomething() {
+     *     console.log('hi!')
+     *   }
+     * }
+     * ```
+     *
+     * @returns The AfterUpdateCommit decorator
+     *
+     */
+    AfterUpdateCommit(opts) {
+        return AfterUpdateCommit(opts);
+    }
+    /**
+     * Shortcut to the AfterDestroy decorator
+     *
+     * ```ts
+     * class User {
+     *   User.AfterDestroy()
+     *   public doSomething() {
+     *     console.log('hi!')
+     *   }
+     * }
+     * ```
+     *
+     * @returns The AfterDestroy decorator
+     *
+     */
+    AfterDestroy() {
+        return AfterDestroy();
+    }
+    /**
+     * Shortcut to the AfterDestroyCommit decorator
+     *
+     * ```ts
+     * class User {
+     *   User.AfterDestroyCommit()
+     *   public doSomething() {
+     *     console.log('hi!')
+     *   }
+     * }
+     * ```
+     *
+     * @returns The AfterDestroyCommit decorator
+     *
+     */
+    AfterDestroyCommit() {
+        return AfterDestroyCommit();
+    }
+}

package/dist/esm/src/decorators/Encrypted.js

@@ -0,0 +1,80 @@
+import InternalEncrypt from '../encrypt/InternalEncrypt.js';
+import DoNotSetEncryptedFieldsDirectly from '../errors/DoNotSetEncryptedFieldsDirectly.js';
+import pascalize from '../helpers/pascalize.js';
+export default function Encrypted(encryptedColumnName) {
+    return function (_, context) {
+        const key = context.name;
+        const encryptedKey = encryptedColumnName || `encrypted${pascalize(key)}`;
+        context.addInitializer(function () {
+            const dreamClass = this.constructor;
+            if (!dreamClass['globallyInitializingDecorators']) {
+                /**
+                 * Modern Javascript applies implicit accessors to instance properties
+                 * that don't have an accessor explicitly defined in the class definition.
+                 * The instance accessors shadow prototype accessors.
+                 * `addInitializer` is called by Decorators after an instance has been fully
+                 * constructed. We leverage this opportunity to delete the instance accessors
+                 * so that the prototype accessors applied by this decorator can be reached.
+                 */
+                delete this[key];
+                return;
+            }
+            if (!Object.getOwnPropertyDescriptor(dreamClass, 'virtualAttributes')) {
+                // This pattern allows `virtualAttributes` on a base STI class and on
+                // child STI classes. The new `virtualAttributes` property will be created
+                // on the child STI class, but it will include all the `virtualAttributes`
+                // already declared on the base STI class.
+                dreamClass['virtualAttributes'] = [...dreamClass['virtualAttributes']];
+            }
+            ;
+            dreamClass['virtualAttributes'].push({
+                property: key,
+                type: 'string',
+            });
+            if (!Object.getOwnPropertyDescriptor(dreamClass, 'explicitUnsafeParamColumns')) {
+                // This pattern allows `explicitUnsafeParamColumns` on a base STI class and on
+                // child STI classes. The new `explicitUnsafeParamColumns` property will be created
+                // on the child STI class, but it will include all the `explicitUnsafeParamColumns`
+                // already declared on the base STI class.
+                dreamClass['explicitUnsafeParamColumns'] = [...dreamClass['explicitUnsafeParamColumns']];
+            }
+            ;
+            dreamClass['explicitUnsafeParamColumns'].push(encryptedKey);
+            const dreamPrototype = Object.getPrototypeOf(this);
+            Object.defineProperty(dreamPrototype, key, {
+                get() {
+                    return InternalEncrypt.decryptColumn(this.getAttribute(encryptedKey));
+                },
+                set(val) {
+                    /**
+                     *
+                     * Modern Javascript sets all properties that do not have an explicit
+                     * assignment within the constructor to undefined in an implicit constructor.
+                     * Since the Dream constructor sets the value of properties of instances of
+                     * classes that extend Dream (e.g. when passing attributes to #new or #create
+                     * or when loading a model via one of the #find methods or #all), we need to
+                     * prevent those properties from being set back to undefined. Since all
+                     * properties corresponding to a database column get a setter, we achieve this
+                     * protection by including a guard in the setters that returns if this
+                     * property is set.
+                     *
+                     */
+                    if (this.columnSetterGuardActivated)
+                        return;
+                    this.setAttribute(encryptedKey, InternalEncrypt.encryptColumn(val));
+                },
+                configurable: false,
+            });
+            Object.defineProperty(dreamPrototype, encryptedKey, {
+                get() {
+                    return this.currentAttributes[encryptedKey];
+                },
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                set(_) {
+                    throw new DoNotSetEncryptedFieldsDirectly(dreamClass, encryptedKey, key);
+                },
+                configurable: false,
+            });
+        });
+    };
+}

package/dist/esm/src/decorators/ReplicaSafe.js

@@ -0,0 +1,9 @@
+import StiChildIncompatibleWithReplicaSafeDecorator from '../errors/sti/StiChildIncompatibleWithReplicaSafeDecorator.js';
+export default function ReplicaSafe() {
+    return function (target) {
+        const dreamClass = target;
+        if (dreamClass['isSTIChild'])
+            throw new StiChildIncompatibleWithReplicaSafeDecorator(dreamClass);
+        dreamClass['replicaSafe'] = true;
+    };
+}