@imqueue/pg-sequelize 4.2.0

package/src/decorators/ColumnIndex.d.ts

@@ -0,0 +1,206 @@
+/*!
+ * @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';
+/**
+ * The property decorator a decorator factory hands back.
+ *
+ * @remarks
+ * Loose on purpose: it stands for the decorator returned by {@link (ColumnIndex:1) | ColumnIndex} and
+ * {@link (NullableIndex:1) | NullableIndex} when either is called with options, whose exact parameter list
+ * differs between TypeScript's legacy and current decorator emit.
+ */
+export type FunctionType = (...args: any[]) => any;
+/**
+ * The index methods Postgres offers, for {@link ColumnIndexOptions.method}.
+ *
+ * @remarks
+ * Postgres uses `BTREE` when nothing is given, and it is the only method with an
+ * ordered key — so it is the one to want unless the data has a shape another method
+ * is built for.
+ */
+export declare enum IndexMethod {
+    /** Balanced tree: equality, ranges and ordering. Postgres's default. */
+    BTREE = "BTREE",
+    /** Hash: equality only, and smaller than a btree for that alone. */
+    HASH = "HASH",
+    /** Generalised search tree: geometric types, ranges, full-text. */
+    GIST = "GIST",
+    /** Space-partitioned GiST: quadtrees, tries and other unbalanced trees. */
+    SPGIST = "SPGIST",
+    /** Inverted index: containment in arrays, `jsonb` and full-text. */
+    GIN = "GIN",
+    /** Block range: huge tables whose values track their physical order. */
+    BRIN = "BRIN"
+}
+/**
+ * Sort direction of an index key, for {@link ColumnIndexOptions.order}.
+ *
+ * @remarks
+ * Rarely worth setting on its own, since a btree can be read backwards — it earns its
+ * keep when several keys sort in mixed directions, which a single-direction index
+ * cannot serve.
+ */
+export declare enum SortOrder {
+    /** Ascending, which is Postgres's default. */
+    ASC = "ASC",
+    /** Descending. */
+    DESC = "DESC"
+}
+/**
+ * The clauses of the `CREATE INDEX` statement that a {@link (ColumnIndex:1) | ColumnIndex} declaration
+ * turns into.
+ *
+ * @remarks
+ * Every field is optional in practice — both decorators take a `Partial` of this, and
+ * an empty object declares a plain btree index on the column. The names follow
+ * Postgres's own `CREATE INDEX` syntax, and the values of the raw-SQL fields are
+ * emitted as written.
+ */
+export interface ColumnIndexOptions {
+    /**
+     * Name of the index.
+     *
+     * @remarks
+     * Defaults to the table, the column and the declaration's position on the model,
+     * so two indices on one column cannot collide. Naming it yourself is what makes
+     * it recognisable later in `EXPLAIN` output and in `pg_indexes`.
+     */
+    name: string;
+    /** Index method. Postgres uses `BTREE` when this is left out. */
+    method: IndexMethod;
+    /**
+     * Builds the index without locking writes out of the table.
+     *
+     * @remarks
+     * Applied to the drop as well as the create. Postgres refuses to run either
+     * inside a transaction, and a concurrent build that fails leaves an invalid
+     * index behind to be dropped by hand — the price of not blocking a live table.
+     */
+    concurrently: boolean;
+    /**
+     * `true` sorts nulls first, `false` sorts them last, and leaving it out follows
+     * Postgres.
+     *
+     * @remarks
+     * Postgres's own default depends on the direction: nulls last for `ASC`, first
+     * for `DESC`. Set it only to match an `ORDER BY` that asks for the other one.
+     */
+    nullsFirst: boolean;
+    /** Sort direction of the index key. */
+    order: SortOrder;
+    /**
+     * Restricts the index to the rows this SQL condition matches.
+     *
+     * @remarks
+     * A partial index: smaller and cheaper to maintain, and used only where the
+     * planner can prove a query's own condition implies this one. Raw SQL, emitted
+     * as written, so the quoting is yours to get right.
+     */
+    predicate: string;
+    /**
+     * Indexes this SQL expression rather than the column.
+     *
+     * @remarks
+     * For filtering on a computed value — `lower("email")` being the standard case,
+     * which nothing but an expression index can serve. Raw SQL, and it replaces the
+     * column as the key rather than joining it.
+     */
+    expression: string;
+    /**
+     * Extra columns to carry in the index without indexing them.
+     *
+     * @remarks
+     * A covering index, so the planner can answer from the index alone instead of
+     * visiting the table. Btree only. Declared but never emitted in earlier
+     * versions.
+     */
+    include: string[];
+    /** Collation of the index key, where it differs from the column's own. */
+    collation: string;
+    /**
+     * Operator class for the key.
+     *
+     * @remarks
+     * How the method compares values: `text_pattern_ops` to make `LIKE 'x%'`
+     * indexable, `jsonb_path_ops` for a narrower GIN index. Emitted as written.
+     */
+    opClass: string;
+    /** Tablespace to build the index in, instead of the database default. */
+    tablespace: string;
+    /**
+     * Leaves an index that already exists alone rather than rebuilding it.
+     *
+     * @remarks
+     * Turns the pass into `CREATE INDEX IF NOT EXISTS` with no drop in front of it,
+     * so an existing index survives even if its declaration has changed since. The
+     * default rebuilds on every sync, which is always correct and always costs a
+     * full build.
+     */
+    safe: boolean;
+    /** Rejects duplicate values, enforcing uniqueness through the index. */
+    unique: boolean;
+}
+/**
+ * Declares an index on a model column, with Postgres's own index options.
+ *
+ * @remarks
+ * `Index` from `sequelize-typescript` is re-exported here and covers the ordinary
+ * cases through sequelize's own sync. This declares the index as a `CREATE INDEX`
+ * statement instead, which is what makes the Postgres-specific clauses reachable —
+ * partial indices, expression keys, operator classes, concurrent builds, covering
+ * columns. `Sequelize.sync()` runs them after the tables and views are in place.
+ *
+ * Declarations accumulate, so a column can carry several, and each is named by its
+ * position unless you name it.
+ *
+ * @param options - The clauses to build into the statement.
+ * @returns A property decorator.
+ * @example
+ * ```typescript
+ * @Table
+ * export class Lead extends BaseModel<Lead> {
+ *     // case-insensitive lookups, over live rows only
+ *     @ColumnIndex({
+ *         expression: 'lower("email")',
+ *         predicate: '"deletedAt" IS NULL',
+ *         unique: true,
+ *     })
+ *     @Column(DataType.STRING)
+ *     public email: string;
+ * }
+ * ```
+ */
+export declare function ColumnIndex(options: Partial<ColumnIndexOptions>): FunctionType;
+/**
+ * Declares a plain btree index on a model column.
+ *
+ * @remarks
+ * The bare form of the decorator, equivalent to calling it with no options. Use the
+ * factory form for anything Postgres-specific.
+ *
+ * @param target - Model prototype the property belongs to.
+ * @param propertyName - Column to index.
+ * @param propertyDescriptor - Unused; present because a decorator receives it.
+ */
+export declare function ColumnIndex(target: any, propertyName: string, propertyDescriptor?: PropertyDescriptor): void;

package/src/decorators/ColumnIndex.js

@@ -0,0 +1,98 @@
+/*!
+ * @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 { addOptions, getOptions } from 'sequelize-typescript';
+/**
+ * The index methods Postgres offers, for {@link ColumnIndexOptions.method}.
+ *
+ * @remarks
+ * Postgres uses `BTREE` when nothing is given, and it is the only method with an
+ * ordered key — so it is the one to want unless the data has a shape another method
+ * is built for.
+ */
+export var IndexMethod;
+(function (IndexMethod) {
+    /** Balanced tree: equality, ranges and ordering. Postgres's default. */
+    IndexMethod["BTREE"] = "BTREE";
+    /** Hash: equality only, and smaller than a btree for that alone. */
+    IndexMethod["HASH"] = "HASH";
+    /** Generalised search tree: geometric types, ranges, full-text. */
+    IndexMethod["GIST"] = "GIST";
+    /** Space-partitioned GiST: quadtrees, tries and other unbalanced trees. */
+    IndexMethod["SPGIST"] = "SPGIST";
+    /** Inverted index: containment in arrays, `jsonb` and full-text. */
+    IndexMethod["GIN"] = "GIN";
+    /** Block range: huge tables whose values track their physical order. */
+    IndexMethod["BRIN"] = "BRIN";
+})(IndexMethod || (IndexMethod = {}));
+/**
+ * Sort direction of an index key, for {@link ColumnIndexOptions.order}.
+ *
+ * @remarks
+ * Rarely worth setting on its own, since a btree can be read backwards — it earns its
+ * keep when several keys sort in mixed directions, which a single-direction index
+ * cannot serve.
+ */
+export var SortOrder;
+(function (SortOrder) {
+    /** Ascending, which is Postgres's default. */
+    SortOrder["ASC"] = "ASC";
+    /** Descending. */
+    SortOrder["DESC"] = "DESC";
+})(SortOrder || (SortOrder = {}));
+export function ColumnIndex(...args) {
+    if (args.length >= 2) {
+        const [target, propertyName, propertyDescriptor] = args;
+        return annotate(target, propertyName, propertyDescriptor);
+    }
+    return (target, propertyName, propertyDescriptor) => {
+        annotate(target, propertyName, propertyDescriptor, args[0]);
+    };
+}
+/**
+ * Appends one index declaration to the model's options.
+ *
+ * @param target - Model prototype the property belongs to.
+ * @param propertyName - Column to index.
+ * @param propertyDescriptor - Unused; present because a decorator receives it.
+ * @param options - The clauses to record for this index.
+ */
+function annotate(target, propertyName, propertyDescriptor, options = {}) {
+    // Optional, because there may be no options bag yet. TypeScript applies
+    // property decorators BEFORE class decorators, so on an ordinary model this
+    // runs before `@Table` has created one, and reading `.indices` off undefined
+    // threw at import time — which made this decorator unusable exactly where it
+    // was meant to be used.
+    const indices = getOptions(target)?.indices || [];
+    addOptions(target, {
+        indices: [
+            ...indices,
+            {
+                column: propertyName,
+                options,
+            },
+        ],
+    });
+}
+//# sourceMappingURL=ColumnIndex.js.map

package/src/decorators/CreatedBy.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Stamps the decorated column with the acting user id on INSERT, taken from the
+ * in-flight IMQ request metadata (`currentMetadata()?.userId`) — so the id never
+ * travels through method arguments and cannot be spoofed by a caller.
+ *
+ * A property decorator, reusable on any model field. The hook is a no-op when
+ * there is no acting user (system / unattributed writes) and never overwrites a
+ * value the application set explicitly.
+ *
+ * Two hooks are registered, because rows are inserted in two ways:
+ *  - instance / single `create()`         → `beforeCreate` (receives the instance)
+ *  - static `Model.bulkCreate(records, …)` → `beforeBulkCreate` (receives the
+ *    built instances; a plain `bulkCreate` does not fire `beforeCreate`, so the
+ *    per-instance hook alone would be bypassed). Sequelize filters the written
+ *    columns down to `options.fields` when the caller supplies it, so an injected
+ *    field is dropped unless also added there.
+ *
+ * Mechanism: a property decorator receives the prototype, but Sequelize hook
+ * decorators must target a static method on the constructor, so generated static
+ * methods are attached to `target.constructor` and registered through the public
+ * `@BeforeCreate` / `@BeforeBulkCreate`. Hooks are installed by
+ * sequelize-typescript's `installHooks` during `Sequelize#addModels`.
+ *
+ * @param target - the decorated model's prototype
+ * @param propertyName - the decorated column property name
+ */
+export declare function CreatedBy(target: any, propertyName: string): void;

package/src/decorators/CreatedBy.js

@@ -0,0 +1,84 @@
+/*!
+ * @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, BeforeCreate } from 'sequelize-typescript';
+/**
+ * Stamps the decorated column with the acting user id on INSERT, taken from the
+ * in-flight IMQ request metadata (`currentMetadata()?.userId`) — so the id never
+ * travels through method arguments and cannot be spoofed by a caller.
+ *
+ * A property decorator, reusable on any model field. The hook is a no-op when
+ * there is no acting user (system / unattributed writes) and never overwrites a
+ * value the application set explicitly.
+ *
+ * Two hooks are registered, because rows are inserted in two ways:
+ *  - instance / single `create()`         → `beforeCreate` (receives the instance)
+ *  - static `Model.bulkCreate(records, …)` → `beforeBulkCreate` (receives the
+ *    built instances; a plain `bulkCreate` does not fire `beforeCreate`, so the
+ *    per-instance hook alone would be bypassed). Sequelize filters the written
+ *    columns down to `options.fields` when the caller supplies it, so an injected
+ *    field is dropped unless also added there.
+ *
+ * Mechanism: a property decorator receives the prototype, but Sequelize hook
+ * decorators must target a static method on the constructor, so generated static
+ * methods are attached to `target.constructor` and registered through the public
+ * `@BeforeCreate` / `@BeforeBulkCreate`. Hooks are installed by
+ * sequelize-typescript's `installHooks` during `Sequelize#addModels`.
+ *
+ * @param target - the decorated model's prototype
+ * @param propertyName - the decorated column property name
+ */
+export function CreatedBy(target, propertyName) {
+    const ctor = target.constructor;
+    const hookName = `__stampCreatedBy$${propertyName}`;
+    const bulkHook = `__stampCreatedByOnBulkCreate$${propertyName}`;
+    if (ctor[hookName]) {
+        return;
+    }
+    ctor[hookName] = function (instance) {
+        const userId = currentMetadata()?.userId;
+        if (userId != null && instance[propertyName] == null) {
+            instance[propertyName] = userId;
+        }
+    };
+    ctor[bulkHook] = 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);
+        }
+    };
+    BeforeCreate(ctor, hookName);
+    BeforeBulkCreate(ctor, bulkHook);
+}
+//# sourceMappingURL=CreatedBy.js.map

package/src/decorators/DeletedBy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Stamps the decorated column with the acting user id on soft-delete (and clears
+ * it on restore), taken from the in-flight IMQ request metadata
+ * (`currentMetadata()?.userId`). Mirrors `@DeletedAt`: set on delete, cleared on
+ * restore, and a delete touches neither `updatedAt` nor an `@UpdatedBy` column.
+ *
+ * A property decorator for paranoid models, reusable on any field. Soft-delete
+ * runs through `Model.destroy`, which Sequelize turns into a `deletedAt`-only
+ * UPDATE whose value hash is built internally and is unreachable from any hook.
+ * So instead of mutating that statement, the `beforeBulkDestroy` hook stamps the
+ * column with a sibling UPDATE over the same still-live rows (same `where`, same
+ * transaction) just before the soft-delete sets `deletedAt`; `beforeBulkRestore`
+ * does the inverse, clearing it as `deletedAt` is cleared.
+ *
+ * The sibling UPDATE runs on `this` — the concrete model the hook fires for,
+ * bound by Sequelize at call time (`runHooks` → `hook.apply(model, ...)`) —
+ * rather than the class captured at decoration time. That lets the decorator be
+ * declared on an abstract base model (e.g. a shared `BaseParanoid`) and still
+ * resolve to the real subclass; the captured constructor would be the
+ * (unregistered) base and break with "model not initialized".
+ *
+ * `hooks: false` avoids hook re-entrancy and keeps the delete from bumping an
+ * `@UpdatedBy` column; `silent: true` keeps it from bumping `updatedAt`, so the
+ * delete writes exactly `deletedBy` + `deletedAt` (like the native paranoid
+ * delete writes only `deletedAt`). No-op when there is no acting user.
+ *
+ * @param target - the decorated model's prototype
+ * @param propertyName - the decorated column property name
+ */
+export declare function DeletedBy(target: any, propertyName: string): void;

package/src/decorators/DeletedBy.js

@@ -0,0 +1,89 @@
+/*!
+ * @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 { BeforeBulkDestroy, BeforeBulkRestore } from 'sequelize-typescript';
+/**
+ * Stamps the decorated column with the acting user id on soft-delete (and clears
+ * it on restore), taken from the in-flight IMQ request metadata
+ * (`currentMetadata()?.userId`). Mirrors `@DeletedAt`: set on delete, cleared on
+ * restore, and a delete touches neither `updatedAt` nor an `@UpdatedBy` column.
+ *
+ * A property decorator for paranoid models, reusable on any field. Soft-delete
+ * runs through `Model.destroy`, which Sequelize turns into a `deletedAt`-only
+ * UPDATE whose value hash is built internally and is unreachable from any hook.
+ * So instead of mutating that statement, the `beforeBulkDestroy` hook stamps the
+ * column with a sibling UPDATE over the same still-live rows (same `where`, same
+ * transaction) just before the soft-delete sets `deletedAt`; `beforeBulkRestore`
+ * does the inverse, clearing it as `deletedAt` is cleared.
+ *
+ * The sibling UPDATE runs on `this` — the concrete model the hook fires for,
+ * bound by Sequelize at call time (`runHooks` → `hook.apply(model, ...)`) —
+ * rather than the class captured at decoration time. That lets the decorator be
+ * declared on an abstract base model (e.g. a shared `BaseParanoid`) and still
+ * resolve to the real subclass; the captured constructor would be the
+ * (unregistered) base and break with "model not initialized".
+ *
+ * `hooks: false` avoids hook re-entrancy and keeps the delete from bumping an
+ * `@UpdatedBy` column; `silent: true` keeps it from bumping `updatedAt`, so the
+ * delete writes exactly `deletedBy` + `deletedAt` (like the native paranoid
+ * delete writes only `deletedAt`). No-op when there is no acting user.
+ *
+ * @param target - the decorated model's prototype
+ * @param propertyName - the decorated column property name
+ */
+export function DeletedBy(target, propertyName) {
+    const ctor = target.constructor;
+    const bulkHook = `__stampBulkDeletedBy$${propertyName}`;
+    const restoreHook = `__clearBulkDeletedBy$${propertyName}`;
+    if (ctor[bulkHook]) {
+        return;
+    }
+    ctor[bulkHook] = async function (options) {
+        const userId = currentMetadata()?.userId;
+        if (userId == null || !options || !options.where) {
+            return;
+        }
+        await this.update({ [propertyName]: userId }, {
+            where: options.where,
+            transaction: options.transaction,
+            hooks: false,
+            silent: true,
+        });
+    };
+    ctor[restoreHook] = async function (options) {
+        if (!options || !options.where) {
+            return;
+        }
+        await this.update({ [propertyName]: null }, {
+            where: options.where,
+            transaction: options.transaction,
+            paranoid: false,
+            hooks: false,
+            silent: true,
+        });
+    };
+    BeforeBulkDestroy(ctor, bulkHook);
+    BeforeBulkRestore(ctor, restoreHook);
+}
+//# sourceMappingURL=DeletedBy.js.map

package/src/decorators/DynamicView.d.ts

@@ -0,0 +1,124 @@
+/*!
+ * 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 IViewDefineOptions } from './View.js';
+/**
+ * Values for a dynamic view's placeholders, keyed by placeholder name.
+ *
+ * @remarks
+ * Values are typed as strings and rendered as quoted SQL constants, so a numeric
+ * placeholder arrives as a quoted number and relies on Postgres casting it. They are
+ * escaped on the way in, which is what makes it safe for one to carry a caller's
+ * input.
+ */
+export interface ViewParams {
+    [name: string]: string;
+}
+/**
+ * Options for a view whose definition is parameterised.
+ */
+export interface IDynamicViewDefineOptions extends IViewDefineOptions {
+    /**
+     * A value for every placeholder the definition names.
+     *
+     * @remarks
+     * These are the defaults. A query may override any of them through
+     * `FindOptions.viewParams`, and what it does not override falls back to here.
+     * Every placeholder must appear in this map, which is checked when the class is
+     * defined.
+     */
+    viewParams: ViewParams;
+    /**
+     * The create statement, with placeholders in it.
+     *
+     * @remarks
+     * Same as the static case except that `@{name}` placeholders are substituted
+     * before the statement is used.
+     */
+    viewDefinition: string;
+    /**
+     * Marks the model as a dynamic view. Set by the decorator, not by you.
+     */
+    isDynamicView?: boolean;
+}
+/**
+ * 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 declare const MATCHER = "@\\{([a-z0-9_]+?)\\}";
+/** {@link MATCHER} compiled to find every placeholder in a definition. */
+export declare const RX_MATCHER: RegExp;
+/** {@link MATCHER} compiled to pull the name out of a single placeholder. */
+export declare const RX_NAME_MATCHER: RegExp;
+/**
+ * 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 declare function DynamicView(options: IDynamicViewDefineOptions): (target: any) => void;