ts-prorm-orm 1.1.0 → 1.2.0

package/dist/decorators/procedure.js

@@ -10,9 +10,18 @@
  * @SqlFunction — like @Procedure but for database functions that RETURN a
  *                value and can be called inside SELECT / WHERE clauses.
  *
- * Both decorators store metadata in a registry. Call
- * ProcedureRegistry.getSQL(target, method) to retrieve the generated DDL,
- * and ProcedureRegistry.call(prorm, target, method, args) to execute.
+ * Both decorators store metadata in a registry. Register the class with
+ * `prorm.registerProcedures(MyProcedures)` and `sync()` will issue the DDL;
+ * `ProcedureRegistry.getSQL(target, method)` returns it if you'd rather run it
+ * yourself, and `ProcedureRegistry.call(prorm, target, method, args)` invokes it.
+ *
+ * Scope note: the `body` option is SQL, and deliberately so. These decorators
+ * generate the CREATE PROCEDURE envelope - name, parameter list, language,
+ * volatility, schema qualification and dialect differences - but the routine's
+ * body is procedural SQL (PL/pgSQL, MySQL's compound statements, PL/SQL) with
+ * no ORM-level equivalent. Everything a query can express belongs in a model
+ * method instead; reach for a stored procedure only when you specifically need
+ * logic to live in the database.
  *
  * Example:
  *
@@ -90,12 +99,27 @@ function SqlFunction(options) {
     };
 }
 // ==================== SQL Generation ====================
+/**
+ * A procedure/function must have a body.
+ *
+ * This used to default to the comment `-- TODO: add procedure body here`, which
+ * produced a syntactically valid but empty routine - so forgetting `body`
+ * silently created a procedure that did nothing, and the mistake only surfaced
+ * when someone called it. Fail at generation time instead.
+ */
+function requireBody(opts, meta, kind) {
+    if (!opts.body || !opts.body.trim()) {
+        throw new Error(`[ORM] @${kind === 'function' ? 'SqlFunction' : 'Procedure'} "${opts.name ?? meta.methodKey}" ` +
+            `has no \`body\`. A stored ${kind} needs its SQL body - there is no meaningful default.`);
+    }
+    return opts.body;
+}
 function buildMysqlProcedure(meta) {
     const opts = meta.options;
     const name = opts.schema ? `\`${opts.schema}\`.\`${opts.name}\`` : `\`${opts.name}\``;
     const params = (opts.params ?? []).map((p) => `${p.mode ?? 'IN'} ${p.name} ${p.type}`).join(', ');
     const drop = opts.replace ? `DROP PROCEDURE IF EXISTS ${name};\n` : '';
-    const body = opts.body ?? '-- TODO: add procedure body here';
+    const body = requireBody(opts, meta, 'procedure');
     return `${drop}CREATE PROCEDURE ${name}(${params})\nBEGIN\n  ${body}\nEND`;
 }
 function buildMysqlFunction(meta) {
@@ -104,7 +128,7 @@ function buildMysqlFunction(meta) {
     const params = (opts.params ?? []).map((p) => `${p.name} ${p.type}`).join(', ');
     const determinism = opts.volatility ?? 'DETERMINISTIC';
     const drop = opts.replace ? `DROP FUNCTION IF EXISTS ${name};\n` : '';
-    const body = opts.body ?? '-- TODO: add function body here';
+    const body = requireBody(opts, meta, 'function');
     return `${drop}CREATE FUNCTION ${name}(${params})\nRETURNS ${opts.returns}\n${determinism}\nBEGIN\n  ${body}\nEND`;
 }
 function buildPostgresProcedure(meta) {
@@ -112,7 +136,7 @@ function buildPostgresProcedure(meta) {
     const name = opts.schema ? `"${opts.schema}"."${opts.name}"` : `"${opts.name}"`;
     const params = (opts.params ?? []).map((p) => `${p.mode ?? 'IN'} ${p.name} ${p.type}`).join(', ');
     const orReplace = opts.replace ? 'OR REPLACE ' : '';
-    const body = opts.body ?? '-- TODO: add procedure body here';
+    const body = requireBody(opts, meta, 'procedure');
     return `CREATE ${orReplace}PROCEDURE ${name}(${params})\nLANGUAGE plpgsql\nAS $$\nBEGIN\n  ${body}\nEND;\n$$`;
 }
 function buildPostgresFunction(meta) {
@@ -122,7 +146,7 @@ function buildPostgresFunction(meta) {
     const language = opts.language ?? 'plpgsql';
     const volatility = opts.volatility ? `\n${opts.volatility}` : '';
     const orReplace = opts.replace ? 'OR REPLACE ' : '';
-    const body = opts.body ?? '-- TODO: add function body here';
+    const body = requireBody(opts, meta, 'function');
     const bodyWrapper = language === 'SQL' ? `$$ ${body} $$` : `$$\nBEGIN\n  ${body}\nEND;\n$$`;
     return `CREATE ${orReplace}FUNCTION ${name}(${params})\nRETURNS ${opts.returns}${volatility}\nLANGUAGE ${language}\nAS ${bodyWrapper}`;
 }

package/dist/decorators/query-options.d.ts

@@ -0,0 +1,527 @@
+/**
+ * Query options and performance hint decorators for the ORM.
+ *
+ * Provides decorators for controlling query execution:
+ * - Query hints (index hints, force index, ignore index)
+ * - Lock options (row locking, timeout, skip locked)
+ * - Statement timeout
+ * - Idle in transaction timeout
+ * - Cursor-based fetching
+ * - FETCH options (FIRST, OFFSET)
+ * - DISTINCT ON (PostgreSQL)
+ * - TABLESAMPLE
+ *
+ * Usage:
+ *
+ *   // Index hints
+ *   @UseIndex('idx_name')
+ *   @ForceIndex('idx_name')
+ *   @IgnoreIndex('idx_name')
+ *   class User extends Model {}
+ *
+ *   // Lock options (method decorator)
+ *   @WithLock({ mode: 'UPDATE', timeout: 5000, skipLocked: true })
+ *   async processOrder(id: number) { ... }
+ *
+ *   // Statement timeout (method decorator)
+ *   @StatementTimeout(30000)
+ *   async runLongQuery() { ... }
+ *
+ *   // Cursor-based fetch
+ *   @Cursor({ holdable: true })
+ *   async *getAllUsers() { ... }
+ *
+ *   // FETCH options
+ *   @Fetch(100)
+ *   @Distinct
+ *   async *getUsers() { ... }
+ *
+ *   // TABLESAMPLE
+ *   @Tablesample({ method: 'BERNOULLI', percentage: 50 })
+ *   async *getSampleUsers() { ... }
+ */
+import 'reflect-metadata';
+/**
+ * Lock mode types
+ */
+export type LockMode = 'UPDATE' | 'SHARE' | 'UPDATE NOWAIT' | 'SHARE NOWAIT' | 'UPDATE SKIP LOCKED';
+/**
+ * Options for @WithLock decorator
+ */
+export interface WithLockOptions {
+    /**
+     * Lock mode
+     * Default: 'UPDATE'
+     */
+    mode?: LockMode;
+    /**
+     * Lock timeout in milliseconds
+     * Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Skip locked rows
+     * Default: false
+     */
+    skipLocked?: boolean;
+    /**
+     * Table aliases for lock (for JOIN locking)
+     */
+    tables?: string[];
+}
+/**
+ * Options for @StatementTimeout decorator
+ */
+export interface StatementTimeoutOptions {
+    /**
+     * Timeout in milliseconds
+     * 0 means no timeout
+     */
+    timeout: number;
+    /**
+     * Whether to set timeout per session or global
+     * Default: 'session'
+     */
+    scope?: 'session' | 'global';
+}
+/**
+ * Options for @IdleInTransactionTimeout decorator
+ */
+export interface IdleInTransactionTimeoutOptions {
+    /**
+     * Timeout in milliseconds
+     */
+    timeout: number;
+    /**
+     * Whether to set timeout per session or global
+     * Default: 'session'
+     */
+    scope?: 'session' | 'global';
+}
+/**
+ * Cursor holdability options
+ */
+export type CursorHoldable = 'HOLD' | 'WITHOUT HOLD';
+/**
+ * Options for @Cursor decorator
+ */
+export interface CursorOptions {
+    /**
+     * Cursor holdability
+     * Default: 'WITHOUT HOLD'
+     */
+    holdable?: CursorHoldable;
+    /**
+     * Cursor name (optional, auto-generated if not provided)
+     */
+    name?: string;
+    /**
+     * Whether to use scroll capability
+     * Default: true
+     */
+    scroll?: boolean;
+}
+/**
+ * Tablesample method types
+ */
+export type TablesampleMethod = 'BERNOULLI' | 'SYSTEM' | 'SYSTEM_TIME';
+/**
+ * Options for @Tablesample decorator
+ */
+export interface TablesampleOptions {
+    /**
+     * Sampling method
+     */
+    method: TablesampleMethod;
+    /**
+     * Percentage of rows to sample (1-100)
+     * For BERNOULLI and SYSTEM
+     */
+    percentage?: number;
+    /**
+     * Number of pages to sample
+     * For SYSTEM method
+     */
+    pages?: number;
+    /**
+     * Seed for reproducible sampling
+     * For BERNOULLI method
+     */
+    seed?: number;
+    /**
+     * Timestamp for SYSTEM_TIME method (PostgreSQL 15+)
+     */
+    timestamp?: Date | string;
+    /**
+     * Repeatable value for consistent samples
+     * For BERNOULLI and SYSTEM
+     */
+    repeatable?: number;
+}
+/**
+ * Query hint types
+ */
+export type QueryHintType = 'USE' | 'FORCE' | 'IGNORE';
+/**
+ * Options for index hint decorators
+ */
+export interface IndexHintOptions {
+    /**
+     * Index name
+     */
+    index: string;
+    /**
+     * Index type (for some databases)
+     */
+    type?: string;
+    /**
+     * For JOIN order hint
+     */
+    order?: 'FIRST' | 'LAST';
+}
+/**
+ * Query options collected from decorators
+ */
+export interface QueryOptions {
+    /**
+     * USE index hint
+     */
+    useIndex?: string[];
+    /**
+     * FORCE index hint
+     */
+    forceIndex?: string[];
+    /**
+     * IGNORE index hint
+     */
+    ignoreIndex?: string[];
+    /**
+     * Lock options
+     */
+    lock?: WithLockOptions;
+    /**
+     * Statement timeout in ms
+     */
+    statementTimeout?: number;
+    /**
+     * Idle transaction timeout in ms
+     */
+    idleInTransactionTimeout?: number;
+    /**
+     * Cursor options
+     */
+    cursor?: CursorOptions;
+    /**
+     * FETCH FIRST limit
+     */
+    fetchFirst?: number;
+    /**
+     * FETCH offset
+     */
+    fetchOffset?: number;
+    /**
+     * DISTINCT ON columns (PostgreSQL)
+     */
+    distinctOn?: string[];
+    /**
+     * Tablesample options
+     */
+    tablesample?: TablesampleOptions;
+    /**
+     * Whether DISTINCT is enabled
+     */
+    distinct?: boolean;
+}
+/**
+ * Decorator to specify USE INDEX hint.
+ * Suggest the optimizer to use a specific index.
+ *
+ * Usage:
+ *
+ *   @UseIndex('idx_user_email')
+ *   @UseIndex(['idx_user_email', 'idx_user_status'])
+ *   class User extends Model {}
+ *
+ * @param index - Index name or array of index names
+ */
+export declare function UseIndex(index: string | string[]): ClassDecorator;
+/**
+ * Decorator to specify FORCE INDEX hint.
+ * Force the optimizer to use a specific index.
+ *
+ * Usage:
+ *
+ *   @ForceIndex('idx_user_email')
+ *   class User extends Model {}
+ *
+ * @param index - Index name
+ */
+export declare function ForceIndex(index: string | string[]): ClassDecorator;
+/**
+ * Decorator to specify IGNORE INDEX hint.
+ * Tell the optimizer to ignore a specific index.
+ *
+ * Usage:
+ *
+ *   @IgnoreIndex('idx_user_email')
+ *   class User extends Model {}
+ *
+ * @param index - Index name
+ */
+export declare function IgnoreIndex(index: string | string[]): ClassDecorator;
+/**
+ * Decorator to set tablesample for query.
+ * Sample a subset of rows for query performance.
+ *
+ * Usage:
+ *
+ *   @Tablesample({ method: 'BERNOULLI', percentage: 50 })
+ *   class User extends Model {}
+ *
+ *   @Tablesample({ method: 'SYSTEM', pages: 100 })
+ *   class User extends Model {}
+ *
+ * @param options - Tablesample options
+ */
+export declare function Tablesample(options: TablesampleOptions): ClassDecorator;
+/**
+ * Decorator to enable DISTINCT ON (PostgreSQL).
+ *
+ * Usage:
+ *
+ *   @Distinct
+ *   class User extends Model {}
+ *
+ *   @DistinctOn(['email'])
+ *   class User extends Model {}
+ *
+ * @param columns - Columns for DISTINCT ON (optional)
+ */
+export declare function Distinct(columns?: string[]): ClassDecorator;
+/**
+ * Alias for @Distinct for DISTINCT ON
+ */
+export declare const DistinctOn: typeof Distinct;
+/**
+ * Decorator to apply row lock to a method.
+ * Provides options for locking rows during query execution.
+ *
+ * Usage:
+ *
+ *   @WithLock({ mode: 'UPDATE', timeout: 5000, skipLocked: true })
+ *   async processOrder(id: number) {
+ *     const order = await Order.findByPk(id, { lock: 'UPDATE' });
+ *     // process order
+ *   }
+ *
+ * @param options - Lock options
+ */
+export declare function WithLock(options?: WithLockOptions): MethodDecorator;
+/**
+ * Decorator to set statement timeout.
+ * Abort queries that take longer than the specified timeout.
+ *
+ * Usage:
+ *
+ *   @StatementTimeout(30000)  // 30 seconds
+ *   async runLongQuery() {
+ *     return await this.query('SELECT * FROM large_table');
+ *   }
+ *
+ * @param timeout - Timeout in milliseconds
+ */
+export declare function StatementTimeout(timeout: number): MethodDecorator;
+/**
+ * Decorator to set idle in transaction timeout.
+ * Abort transactions that are idle for longer than the specified timeout.
+ *
+ * Usage:
+ *
+ *   @IdleInTransactionTimeout(60000)  // 1 minute
+ *   async runTransaction() {
+ *     // long running transaction
+ *   }
+ *
+ * @param timeout - Timeout in milliseconds
+ */
+export declare function IdleInTransactionTimeout(timeout: number): MethodDecorator;
+/**
+ * Decorator to use cursor-based fetching.
+ * Useful for processing large result sets in batches.
+ *
+ * Usage:
+ *
+ *   @Cursor({ holdable: true })
+ *   async *getAllUsers() {
+ *     for await (const user of this.findAll({ cursor: true })) {
+ *       yield user;
+ *     }
+ *   }
+ *
+ * @param options - Cursor options
+ */
+export declare function Cursor(options?: CursorOptions): MethodDecorator;
+/**
+ * Decorator to set FETCH FIRST limit.
+ * Limits the number of rows returned by a query.
+ *
+ * Usage:
+ *
+ *   @Fetch(100)
+ *   async *getTopUsers() {
+ *     return await User.findAll({ limit: 100 });
+ *   }
+ *
+ * @param limit - Number of rows to fetch
+ */
+export declare function Fetch(limit: number): MethodDecorator;
+/**
+ * Decorator to set FETCH with offset.
+ * Useful for pagination.
+ *
+ * Usage:
+ *
+ *   @Fetch({ first: 100, offset: 50 })
+ *   async *getPageUsers() {
+ *     return await User.findAll({ offset: 50, limit: 100 });
+ *   }
+ *
+ * @param options - Fetch options with limit and optional offset
+ */
+export declare function FetchWith(options: {
+    first: number;
+    offset?: number;
+}): MethodDecorator;
+/**
+ * Get query hints for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Query hints or undefined
+ */
+export declare function getQueryHints(target: object): {
+    useIndex?: string[];
+    forceIndex?: string[];
+    ignoreIndex?: string[];
+} | undefined;
+/**
+ * Get lock options for a method.
+ *
+ * @param target - The target object
+ * @param propertyKey - The property key
+ * @returns Lock options or undefined
+ */
+export declare function getLockOptions(target: object, propertyKey: string | symbol): WithLockOptions | undefined;
+/**
+ * Get statement timeout for a method.
+ *
+ * @param target - The target object
+ * @param propertyKey - The property key
+ * @returns Statement timeout options or undefined
+ */
+export declare function getStatementTimeout(target: object, propertyKey: string | symbol): StatementTimeoutOptions | undefined;
+/**
+ * Get idle transaction timeout for a method.
+ *
+ * @param target - The target object
+ * @param propertyKey - The property key
+ * @returns Idle transaction timeout options or undefined
+ */
+export declare function getIdleInTransactionTimeout(target: object, propertyKey: string | symbol): IdleInTransactionTimeoutOptions | undefined;
+/**
+ * Get cursor options for a method.
+ *
+ * @param target - The target object
+ * @param propertyKey - The property key
+ * @returns Cursor options or undefined
+ */
+export declare function getCursorOptions(target: object, propertyKey: string | symbol): CursorOptions | undefined;
+/**
+ * Get FETCH options for a method.
+ *
+ * @param target - The target object
+ * @param propertyKey - The property key
+ * @returns FETCH options or undefined
+ */
+export declare function getFetchOptions(target: object, propertyKey: string | symbol): {
+    limit: number;
+    offset: number;
+} | undefined;
+/**
+ * Get DISTINCT ON columns for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns DISTINCT ON columns or undefined
+ */
+export declare function getDistinctOnColumns(target: object): string[] | undefined;
+/**
+ * Get tablesample options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Tablesample options or undefined
+ */
+export declare function getTablesampleOptions(target: object): TablesampleOptions | undefined;
+/**
+ * Check if DISTINCT is enabled for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns True if DISTINCT is enabled
+ */
+export declare function isDistinctEnabled(target: object): boolean;
+/**
+ * Generate index hint SQL.
+ *
+ * @param hints - Query hints
+ * @param dialect - Database dialect
+ * @returns SQL string or undefined
+ */
+export declare function generateIndexHintSQL(hints: {
+    useIndex?: string[];
+    forceIndex?: string[];
+    ignoreIndex?: string[];
+}, dialect: string): string | undefined;
+/**
+ * Generate lock SQL.
+ *
+ * @param options - Lock options
+ * @returns SQL FOR clause or undefined
+ */
+export declare function generateLockSQL(options: WithLockOptions): string | undefined;
+/**
+ * Generate statement timeout SQL.
+ *
+ * @param timeout - Timeout in milliseconds
+ * @param scope - Session or global
+ * @returns SQL string
+ */
+export declare function generateStatementTimeoutSQL(timeout: number, scope?: 'session' | 'global'): string;
+/**
+ * Generate idle in transaction timeout SQL.
+ *
+ * @param timeout - Timeout in milliseconds
+ * @param scope - Session or global
+ * @returns SQL string
+ */
+export declare function generateIdleInTransactionTimeoutSQL(timeout: number, scope?: 'session' | 'global'): string;
+/**
+ * Generate tablesample SQL.
+ *
+ * @param options - Tablesample options
+ * @returns SQL TABLESAMPLE clause
+ */
+export declare function generateTablesampleSQL(options: TablesampleOptions): string;
+/**
+ * Generate DISTINCT ON SQL (PostgreSQL).
+ *
+ * @param columns - DISTINCT ON columns
+ * @returns SQL DISTINCT ON clause
+ */
+export declare function generateDistinctOnSQL(columns: string[]): string;
+/**
+ * Generate cursor SQL.
+ *
+ * @param options - Cursor options
+ * @param name - Cursor name (optional)
+ * @returns SQL DECLARE CURSOR statement
+ */
+export declare function generateCursorSQL(options: CursorOptions, name?: string): string;
+export type { WithLockOptions as WithLockOptionsType, LockMode as LockModeType, StatementTimeoutOptions as StatementTimeoutOptionsType, IdleInTransactionTimeoutOptions as IdleInTransactionTimeoutOptionsType, CursorOptions as CursorOptionsType, TablesampleOptions as TablesampleOptionsType, IndexHintOptions as IndexHintOptionsType, QueryOptions as QueryOptionsType, };