@imqueue/pg-sequelize 4.2.0

package/src/decorators/DynamicView.js

@@ -0,0 +1,113 @@
+/*!
+ * I'm Queue Software Project
+ * Copyright (C) 2025  imqueue.com <support@imqueue.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * If you want to use this code in a closed source (commercial) project, you can
+ * purchase a proprietary commercial license. Please contact us at
+ * <support@imqueue.com> to get commercial licensing options.
+ */
+import 'reflect-metadata';
+import { addOptions, setModelName } from 'sequelize-typescript';
+import {} from './View.js';
+/**
+ * The placeholder pattern as a source string: `@{name}`, where the name is letters,
+ * digits and underscores.
+ *
+ * @remarks
+ * Exported so a service can compile its own matcher — to validate a definition of its
+ * own, say — rather than hard-coding the syntax a second time.
+ */
+export const MATCHER = '@\\{([a-z0-9_]+?)\\}';
+/** {@link MATCHER} compiled to find every placeholder in a definition. */
+export const RX_MATCHER = new RegExp(MATCHER, 'gi');
+/** {@link MATCHER} compiled to pull the name out of a single placeholder. */
+export const RX_NAME_MATCHER = new RegExp(MATCHER, 'i');
+/**
+ * Declares a model to be a view whose definition is parameterised per query.
+ *
+ * @remarks
+ * Everything `View` does, plus placeholders. The definition may carry `@{name}`
+ * markers, every finder accepts `viewParams` to fill them, and the select-query
+ * generator substitutes them and splices the resulting statement into the query — as
+ * the `FROM` target, or as a joined subquery when the view is reached through an
+ * `include`. One model then serves a family of views that differ only by a constant,
+ * which is the alternative to defining one view per variant in a migration.
+ *
+ * Every placeholder must have a default in `viewParams`. That is checked while the
+ * class is being defined, so a missing one is an error at import rather than a
+ * malformed statement at query time.
+ *
+ * Values are escaped, so a parameter can carry a caller's input. Anything that is not
+ * a number or a string becomes `NULL`.
+ *
+ * @param options - Model options carrying the definition and the parameter defaults.
+ * @returns A class decorator.
+ * @throws TypeError when the definition is missing or blank, or when it names a
+ *   placeholder that `viewParams` does not.
+ * @example
+ * ```typescript
+ * @DynamicView({
+ *     viewDefinition: `
+ *         CREATE OR REPLACE VIEW "ProductRevenue" AS
+ *         SELECT "productId" AS "id", SUM("payment") AS "revenue"
+ *           FROM "Order"
+ *          WHERE "currency" = @{currency}
+ *          GROUP BY "productId"
+ *     `,
+ *     viewParams: { currency: 'USD' },
+ *     freezeTableName: true,
+ *     timestamps: false,
+ * })
+ * export class ProductRevenue extends BaseModel<ProductRevenue> {
+ *     @PrimaryKey
+ *     @Column(DataType.BIGINT)
+ *     declare public id: number;
+ * }
+ *
+ * // the same model, read in another currency
+ * const rows = await ProductRevenue.findAll({
+ *     viewParams: { currency: 'EUR' },
+ * });
+ * ```
+ */
+export function DynamicView(options) {
+    if (!options || !options.viewDefinition || !options.viewDefinition.trim()) {
+        throw new TypeError('View definition is missing!');
+    }
+    // we are dynamic, no choice here!
+    options.isDynamicView = true;
+    const viewDef = options.viewDefinition || '';
+    const viewParams = options.viewParams || {};
+    (viewDef.match(RX_MATCHER) || []).forEach(param => {
+        const [, name] = param.match(RX_NAME_MATCHER) || ['', ''];
+        if (typeof viewParams[name] !== 'string') {
+            throw new TypeError(`View definition contains param '${name}', but it was not provided`);
+        }
+    });
+    return (target) => annotate(target, options);
+}
+/**
+ * Registers the model under its own name and records the view options on it.
+ *
+ * @param target - Model class being decorated.
+ * @param options - View definition options, marked as a view in place.
+ */
+function annotate(target, options) {
+    Object.assign(options, { treatAsView: true });
+    setModelName(target.prototype, options.modelName || target.name);
+    addOptions(target.prototype, options);
+}
+//# sourceMappingURL=DynamicView.js.map

package/src/decorators/Emittable.d.ts

@@ -0,0 +1,39 @@
+/*!
+ * @imqueue/pg-sequelize - Sequelize ORM refines for @imqueue
+ *
+ * I'm Queue Software Project
+ * Copyright (C) 2025  imqueue.com <support@imqueue.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * If you want to use this code in a closed source (commercial) project, you can
+ * purchase a proprietary commercial license. Please contact us at
+ * <support@imqueue.com> to get commercial licensing options.
+ */
+import 'reflect-metadata';
+/**
+ * Placeholder for change notifications, which are not implemented.
+ *
+ * @remarks
+ * The intent was to attach a trigger that publishes row changes through Postgres
+ * `NOTIFY`. The body is empty: applying this to a model does nothing whatever, and
+ * nothing about a model changes by carrying it. It is unfinished work that happens to
+ * be exported, not a switch that is off.
+ *
+ * What exists today: `@imqueue/pg-pubsub` is the `LISTEN`/`NOTIFY` client, and
+ * `@imqueue/pg-prisma` ships the change-notify triggers for the Prisma stack.
+ *
+ * @param _target - The model class, which is ignored.
+ */
+export declare function Emittable(_target: any): void;

package/src/decorators/Emittable.js

@@ -0,0 +1,42 @@
+/*!
+ * @imqueue/pg-sequelize - Sequelize ORM refines for @imqueue
+ *
+ * I'm Queue Software Project
+ * Copyright (C) 2025  imqueue.com <support@imqueue.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * If you want to use this code in a closed source (commercial) project, you can
+ * purchase a proprietary commercial license. Please contact us at
+ * <support@imqueue.com> to get commercial licensing options.
+ */
+import 'reflect-metadata';
+/**
+ * Placeholder for change notifications, which are not implemented.
+ *
+ * @remarks
+ * The intent was to attach a trigger that publishes row changes through Postgres
+ * `NOTIFY`. The body is empty: applying this to a model does nothing whatever, and
+ * nothing about a model changes by carrying it. It is unfinished work that happens to
+ * be exported, not a switch that is off.
+ *
+ * What exists today: `@imqueue/pg-pubsub` is the `LISTEN`/`NOTIFY` client, and
+ * `@imqueue/pg-prisma` ships the change-notify triggers for the Prisma stack.
+ *
+ * @param _target - The model class, which is ignored.
+ */
+export function Emittable(_target) {
+    // todo: implement
+}
+//# sourceMappingURL=Emittable.js.map

package/src/decorators/NullableIndex.d.ts

@@ -0,0 +1,77 @@
+/*!
+ * @imqueue/pg-sequelize - Sequelize ORM refines for @imqueue
+ *
+ * I'm Queue Software Project
+ * Copyright (C) 2025  imqueue.com <support@imqueue.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * If you want to use this code in a closed source (commercial) project, you can
+ * purchase a proprietary commercial license. Please contact us at
+ * <support@imqueue.com> to get commercial licensing options.
+ */
+import { type ColumnIndexOptions, type FunctionType } from './ColumnIndex.js';
+/**
+ * What {@link (NullableIndex:1) | NullableIndex} accepts: every {@link ColumnIndexOptions} field except
+ * `expression`, which it sets itself.
+ */
+export type NullableColumnIndexOptions = Omit<ColumnIndexOptions, 'expression'>;
+/**
+ * Declares a pair of partial indices on a nullable column, one for the rows where it
+ * is null and one for the rows where it is not.
+ *
+ * @remarks
+ * Two narrow indices instead of one wide one. Each covers only its half of the table,
+ * so `WHERE "col" IS NULL` and `WHERE "col" IS NOT NULL` each get an index sized to
+ * the rows they actually match — which is the point on a column where one of the two
+ * halves is much smaller than the other.
+ *
+ * Usable bare or as a factory, exactly like {@link (ColumnIndex:1) | ColumnIndex}. The factory form used
+ * to build both halves from one options object that it mutated in place, and
+ * {@link (ColumnIndex:1) | ColumnIndex} stores that object by reference — so both declarations ended up
+ * pointing at the same object, both saying `IS NOT NULL`, and neither carrying a
+ * predicate at all. What you got was two identical non-partial indices. It now builds
+ * a fresh options object per half, keeps a predicate of your own by combining it with
+ * the null test, and suffixes a name of your own so the two halves cannot collide.
+ *
+ * @param args - Nothing, when used bare. The options, when used as a factory.
+ * @returns A property decorator, when used as a factory.
+ * @example
+ * ```typescript
+ * @Table
+ * export class Lead extends BaseModel<Lead> {
+ *     @NullableIndex
+ *     @Column(DataType.DATE)
+ *     public closedAt: Date;
+ *
+ *     @NullableIndex({ name: 'lead_assignee', concurrently: true })
+ *     @Column(DataType.BIGINT)
+ *     public assigneeId: number;
+ * }
+ * ```
+ */
+export declare function NullableIndex(options: Partial<NullableColumnIndexOptions>): FunctionType;
+/**
+ * Declares the pair of partial indices with no options of their own.
+ *
+ * @remarks
+ * The bare form. Each half is a partial index keyed on the null test itself, so it
+ * serves `IS NULL` and `IS NOT NULL` lookups; use the factory form to add a method,
+ * a name, or a predicate of your own.
+ *
+ * @param target - Model prototype the property belongs to.
+ * @param propertyName - Nullable column to split.
+ * @param propertyDescriptor - Unused; present because a decorator receives it.
+ */
+export declare function NullableIndex(target: any, propertyName: string, propertyDescriptor?: PropertyDescriptor): void;

package/src/decorators/NullableIndex.js

@@ -0,0 +1,64 @@
+/*!
+ * @imqueue/pg-sequelize - Sequelize ORM refines for @imqueue
+ *
+ * I'm Queue Software Project
+ * Copyright (C) 2025  imqueue.com <support@imqueue.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * If you want to use this code in a closed source (commercial) project, you can
+ * purchase a proprietary commercial license. Please contact us at
+ * <support@imqueue.com> to get commercial licensing options.
+ */
+import { ColumnIndex, } from './ColumnIndex.js';
+export function NullableIndex(...args) {
+    if (args.length >= 2) {
+        const [target, propertyName, propertyDescriptor] = args;
+        annotate(target, propertyName, propertyDescriptor);
+        return;
+    }
+    return (target, propertyName, propertyDescriptor) => {
+        annotate(target, propertyName, propertyDescriptor, args[0]);
+    };
+}
+/**
+ * Declares the two halves of the pair.
+ *
+ * @param target - Model prototype the property belongs to.
+ * @param propertyName - Column the pair is declared on.
+ * @param propertyDescriptor - Passed through to {@link (ColumnIndex:1) | ColumnIndex}.
+ * @param options - Options to apply to both halves.
+ */
+function annotate(target, propertyName, propertyDescriptor, options = {}) {
+    for (const isNull of [true, false]) {
+        const test = `"${propertyName}" IS ${isNull ? '' : 'NOT '}NULL`;
+        // A fresh object per half: ColumnIndex keeps what it is given by
+        // reference, so two halves sharing one object are two halves with
+        // whatever the second one wrote.
+        const half = {
+            ...options,
+            expression: test,
+            // A predicate of the caller's own is kept rather than replaced —
+            // splitting the rows is what this adds, not what it overrides.
+            predicate: options.predicate
+                ? `(${options.predicate}) AND ${test}`
+                : test,
+        };
+        if (options.name) {
+            half.name = `${options.name}${isNull ? '' : '_not'}_null`;
+        }
+        ColumnIndex(half)(target, propertyName, propertyDescriptor);
+    }
+}
+//# sourceMappingURL=NullableIndex.js.map

package/src/decorators/UpdatedBy.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Stamps the decorated column with the acting user id on INSERT and UPDATE,
+ * taken from the in-flight IMQ request metadata (`currentMetadata()?.userId`).
+ *
+ * A property decorator, reusable on any model field. It mirrors `@UpdatedAt`:
+ *  - on INSERT it is set to the creating actor (just as `updatedAt` is set equal
+ *    to `createdAt` on insert), without overwriting an explicit value;
+ *  - on UPDATE it always overwrites with the current actor — "last modified by"
+ *    must reflect who actually ran the update and not be caller-spoofable.
+ *
+ * Four hooks are registered, because models are written in four ways:
+ *  - single INSERT                    → `beforeCreate` (set-if-empty)
+ *  - `Model.bulkCreate(records, …)`   → `beforeBulkCreate` (set-if-empty on the
+ *    built instances; a plain `bulkCreate` does not fire `beforeCreate`, so the
+ *    per-instance hook alone would be bypassed)
+ *  - instance `save()` / `update()`   → `beforeUpdate` (receives the instance)
+ *  - static `Model.update(values, …)` → `beforeBulkUpdate` (receives options;
+ *    the values to write live on `options.attributes`, and Sequelize filters the
+ *    written columns down to `options.fields`, computed before this hook from the
+ *    caller's values — so an injected field is dropped unless also added there).
+ *
+ * No-op when there is no acting user (system / unattributed writes).
+ *
+ * @param target - the decorated model's prototype
+ * @param propertyName - the decorated column property name
+ */
+export declare function UpdatedBy(target: any, propertyName: string): void;

package/src/decorators/UpdatedBy.js

@@ -0,0 +1,105 @@
+/*!
+ * @imqueue/pg-sequelize - Sequelize ORM refines for @imqueue
+ *
+ * I'm Queue Software Project
+ * Copyright (C) 2025  imqueue.com <support@imqueue.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * If you want to use this code in a closed source (commercial) project, you can
+ * purchase a proprietary commercial license. Please contact us at
+ * <support@imqueue.com> to get commercial licensing options.
+ */
+import { currentMetadata } from '@imqueue/rpc';
+import { BeforeBulkCreate, BeforeBulkUpdate, BeforeCreate, BeforeUpdate, } from 'sequelize-typescript';
+/**
+ * Stamps the decorated column with the acting user id on INSERT and UPDATE,
+ * taken from the in-flight IMQ request metadata (`currentMetadata()?.userId`).
+ *
+ * A property decorator, reusable on any model field. It mirrors `@UpdatedAt`:
+ *  - on INSERT it is set to the creating actor (just as `updatedAt` is set equal
+ *    to `createdAt` on insert), without overwriting an explicit value;
+ *  - on UPDATE it always overwrites with the current actor — "last modified by"
+ *    must reflect who actually ran the update and not be caller-spoofable.
+ *
+ * Four hooks are registered, because models are written in four ways:
+ *  - single INSERT                    → `beforeCreate` (set-if-empty)
+ *  - `Model.bulkCreate(records, …)`   → `beforeBulkCreate` (set-if-empty on the
+ *    built instances; a plain `bulkCreate` does not fire `beforeCreate`, so the
+ *    per-instance hook alone would be bypassed)
+ *  - instance `save()` / `update()`   → `beforeUpdate` (receives the instance)
+ *  - static `Model.update(values, …)` → `beforeBulkUpdate` (receives options;
+ *    the values to write live on `options.attributes`, and Sequelize filters the
+ *    written columns down to `options.fields`, computed before this hook from the
+ *    caller's values — so an injected field is dropped unless also added there).
+ *
+ * No-op when there is no acting user (system / unattributed writes).
+ *
+ * @param target - the decorated model's prototype
+ * @param propertyName - the decorated column property name
+ */
+export function UpdatedBy(target, propertyName) {
+    const ctor = target.constructor;
+    const createHook = `__stampUpdatedByOnCreate$${propertyName}`;
+    const bulkCreateHook = `__stampUpdatedByOnBulkCreate$${propertyName}`;
+    const singleHook = `__stampUpdatedBy$${propertyName}`;
+    const bulkHook = `__stampBulkUpdatedBy$${propertyName}`;
+    if (ctor[singleHook]) {
+        return;
+    }
+    ctor[createHook] = function (instance) {
+        const userId = currentMetadata()?.userId;
+        if (userId != null && instance[propertyName] == null) {
+            instance[propertyName] = userId;
+        }
+    };
+    ctor[bulkCreateHook] = function (instances, options) {
+        const userId = currentMetadata()?.userId;
+        if (userId == null || !Array.isArray(instances)) {
+            return;
+        }
+        for (const instance of instances) {
+            if (instance && instance[propertyName] == null) {
+                instance[propertyName] = userId;
+            }
+        }
+        if (options &&
+            Array.isArray(options.fields) &&
+            !options.fields.includes(propertyName)) {
+            options.fields.push(propertyName);
+        }
+    };
+    ctor[singleHook] = function (instance) {
+        const userId = currentMetadata()?.userId;
+        if (userId != null) {
+            instance[propertyName] = userId;
+        }
+    };
+    ctor[bulkHook] = function (options) {
+        const userId = currentMetadata()?.userId;
+        if (userId == null || !options || !options.attributes) {
+            return;
+        }
+        options.attributes[propertyName] = userId;
+        if (Array.isArray(options.fields) &&
+            !options.fields.includes(propertyName)) {
+            options.fields.push(propertyName);
+        }
+    };
+    BeforeCreate(ctor, createHook);
+    BeforeBulkCreate(ctor, bulkCreateHook);
+    BeforeUpdate(ctor, singleHook);
+    BeforeBulkUpdate(ctor, bulkHook);
+}
+//# sourceMappingURL=UpdatedBy.js.map

package/src/decorators/View.d.ts

@@ -0,0 +1,87 @@
+/*!
+ * @imqueue/pg-sequelize - Sequelize ORM refines for @imqueue
+ *
+ * I'm Queue Software Project
+ * Copyright (C) 2025  imqueue.com <support@imqueue.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * If you want to use this code in a closed source (commercial) project, you can
+ * purchase a proprietary commercial license. Please contact us at
+ * <support@imqueue.com> to get commercial licensing options.
+ */
+import 'reflect-metadata';
+import { type ModelOptions } from 'sequelize';
+/**
+ * Sequelize's model options, plus the SQL that defines the view.
+ */
+export interface IViewDefineOptions extends ModelOptions {
+    /**
+     * The complete create statement for the view.
+     *
+     * @remarks
+     * Executed exactly as written, so it carries its own keywords — and writing it as
+     * `CREATE OR REPLACE VIEW` is what makes `sync({ withoutDrop: true })` an option
+     * later, which views that depend on each other need. The name it declares has to
+     * match the model's table name; that is checked before anything runs.
+     */
+    viewDefinition: string;
+}
+/**
+ * Declares a model to be a database view rather than a table.
+ *
+ * @remarks
+ * Does for a view what `Table` does for a table, and sets the flag the rest of the
+ * package keys off: the model is skipped by the table sync, created and dropped with
+ * view statements, and has its numeric columns re-cast after every finder, since a
+ * view returns them as strings.
+ *
+ * Two ordinary model options matter more here than they look. `freezeTableName` stops
+ * sequelize pluralising the model name, which has to match the name inside the
+ * definition. And `timestamps: false` stops it selecting `createdAt` and `updatedAt`,
+ * which a view has no reason to have. A view model may also extend another model
+ * instead of `BaseModel`, which is the shortest way to reuse a table's column
+ * declarations for a view over the same columns.
+ *
+ * Declared columns are a subset of what the view selects: anything the view returns
+ * and the model does not declare is simply not mapped.
+ *
+ * @param options - The definition SQL alone, or model options carrying it.
+ * @returns A class decorator.
+ * @throws TypeError when there is no definition, or it is blank. The string form used
+ *   to skip that check, and an options object without the property threw an unhelpful
+ *   error from reading it.
+ * @example
+ * ```typescript
+ * @View({
+ *     viewDefinition: `
+ *         CREATE OR REPLACE VIEW "ProductRevenue" AS
+ *         SELECT "productId" AS "id", SUM("payment") AS "revenue"
+ *           FROM "Order"
+ *          GROUP BY "productId"
+ *     `,
+ *     freezeTableName: true,
+ *     timestamps: false,
+ * })
+ * export class ProductRevenue extends BaseModel<ProductRevenue> {
+ *     @PrimaryKey
+ *     @Column(DataType.BIGINT)
+ *     declare public id: number;
+ *
+ *     @Column(DataType.DECIMAL(12, 2))
+ *     declare public revenue: number;
+ * }
+ * ```
+ */
+export declare function View(options: IViewDefineOptions | string): (target: any) => void;

package/src/decorators/View.js

@@ -0,0 +1,93 @@
+/*!
+ * @imqueue/pg-sequelize - Sequelize ORM refines for @imqueue
+ *
+ * I'm Queue Software Project
+ * Copyright (C) 2025  imqueue.com <support@imqueue.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ * If you want to use this code in a closed source (commercial) project, you can
+ * purchase a proprietary commercial license. Please contact us at
+ * <support@imqueue.com> to get commercial licensing options.
+ */
+import 'reflect-metadata';
+import {} from 'sequelize';
+import { addOptions, setModelName } from 'sequelize-typescript';
+/**
+ * Declares a model to be a database view rather than a table.
+ *
+ * @remarks
+ * Does for a view what `Table` does for a table, and sets the flag the rest of the
+ * package keys off: the model is skipped by the table sync, created and dropped with
+ * view statements, and has its numeric columns re-cast after every finder, since a
+ * view returns them as strings.
+ *
+ * Two ordinary model options matter more here than they look. `freezeTableName` stops
+ * sequelize pluralising the model name, which has to match the name inside the
+ * definition. And `timestamps: false` stops it selecting `createdAt` and `updatedAt`,
+ * which a view has no reason to have. A view model may also extend another model
+ * instead of `BaseModel`, which is the shortest way to reuse a table's column
+ * declarations for a view over the same columns.
+ *
+ * Declared columns are a subset of what the view selects: anything the view returns
+ * and the model does not declare is simply not mapped.
+ *
+ * @param options - The definition SQL alone, or model options carrying it.
+ * @returns A class decorator.
+ * @throws TypeError when there is no definition, or it is blank. The string form used
+ *   to skip that check, and an options object without the property threw an unhelpful
+ *   error from reading it.
+ * @example
+ * ```typescript
+ * @View({
+ *     viewDefinition: `
+ *         CREATE OR REPLACE VIEW "ProductRevenue" AS
+ *         SELECT "productId" AS "id", SUM("payment") AS "revenue"
+ *           FROM "Order"
+ *          GROUP BY "productId"
+ *     `,
+ *     freezeTableName: true,
+ *     timestamps: false,
+ * })
+ * export class ProductRevenue extends BaseModel<ProductRevenue> {
+ *     @PrimaryKey
+ *     @Column(DataType.BIGINT)
+ *     declare public id: number;
+ *
+ *     @Column(DataType.DECIMAL(12, 2))
+ *     declare public revenue: number;
+ * }
+ * ```
+ */
+export function View(options) {
+    if (typeof options === 'string') {
+        options = { viewDefinition: options };
+    }
+    if (!options || !options.viewDefinition || !options.viewDefinition.trim()) {
+        throw new TypeError('View definition is missing!');
+    }
+    return (target) => annotate(target, options);
+}
+/**
+ * Registers the model under its own name and records the view options on it.
+ *
+ * @param target - Model class being decorated.
+ * @param options - View definition options, marked as a view in place.
+ */
+function annotate(target, options) {
+    Object.assign(options, { treatAsView: true });
+    setModelName(target.prototype, options.modelName || target.name);
+    addOptions(target.prototype, options);
+}
+//# sourceMappingURL=View.js.map