ts-prorm-orm 1.1.0 → 1.2.0

package/dist/decorators/timezone.d.ts

@@ -0,0 +1,319 @@
+/**
+ * Timezone Decorator for the ORM
+ *
+ * Provides automatic timezone conversion for date/time columns.
+ * Supports column-level, table-level, and database-level timezone configuration.
+ *
+ * Usage:
+ *
+ * // Column-level timezone
+ * @Timezone('UTC')  // Store as UTC, convert on read/write
+ * createdAt: Date;
+ *
+ * @Timezone('America/New_York')  // Eastern time
+ * orderPlacedAt: Date;
+ *
+ * @Timezone('Europe/London')  // British time
+ * updatedAt: Date;
+ *
+ * // Auto-detect from user context
+ * @Timezone({ from: 'user' })
+ * lastLoginAt: Date;
+ *
+ * // With format options
+ * @Timezone({
+ *   zone: 'UTC',
+ *   format: 'ISO',  // 'ISO', 'DATE', 'DATETIME', 'TIMESTAMP'
+ *   storeAs: 'utc'  // 'utc', 'local', 'string'
+ * })
+ * timestamp: Date;
+ *
+ * // Table-level default timezone
+ * @Table({ timezone: 'America/Los_Angeles' })
+ * class WestCoastOrder extends Model {}
+ *
+ * // Database-level timezone setting
+ * @DatabaseSetting('timezone', 'UTC')
+ */
+import 'reflect-metadata';
+/**
+ * Output format for timezone conversion
+ */
+export type TimezoneFormat = 'ISO' | 'DATE' | 'DATETIME' | 'TIMESTAMP';
+/**
+ * Storage format for timezone data
+ */
+export type TimezoneStoreAs = 'utc' | 'local' | 'string';
+/**
+ * Timezone source - where to get the timezone
+ */
+export type TimezoneSource = string | {
+    from: 'user' | 'request' | 'context';
+};
+/**
+ * Options for timezone decorator at column level
+ */
+export interface TimezoneOptions {
+    /**
+     * Timezone name (e.g., 'UTC', 'America/New_York')
+     * or source configuration for auto-detection
+     */
+    zone?: TimezoneSource;
+    /**
+     * Output format when reading from database
+     * - 'ISO': ISO 8601 string (2024-01-15T10:30:00.000Z)
+     * - 'DATE': Date only string (2024-01-15)
+     * - 'DATETIME': Date and time string (2024-01-15 10:30:00)
+     * - 'TIMESTAMP': Unix timestamp in milliseconds
+     */
+    format?: TimezoneFormat;
+    /**
+     * How to store timezone data in database
+     * - 'utc': Store as UTC (recommended)
+     * - 'local': Store as local time
+     * - 'string': Store as timezone-aware string
+     */
+    storeAs?: TimezoneStoreAs;
+    /**
+     * Column name in the database (if different from property name)
+     */
+    column?: string;
+    /**
+     * Whether to convert on read (default: true)
+     */
+    convertOnRead?: boolean;
+    /**
+     * Whether to convert on write (default: true)
+     */
+    convertOnWrite?: boolean;
+}
+/**
+ * Table-level timezone options
+ */
+export interface TableTimezoneOptions {
+    /**
+     * Default timezone for all date columns in the table
+     */
+    timezone?: string;
+    /**
+     * Default format for date columns
+     */
+    defaultFormat?: TimezoneFormat;
+    /**
+     * Default storage format
+     */
+    defaultStoreAs?: TimezoneStoreAs;
+}
+/**
+ * Metadata stored for timezone-decorated fields
+ */
+export interface TimezoneFieldMeta {
+    /**
+     * The property name (class field name)
+     */
+    field: string;
+    /**
+     * Database column name
+     */
+    column: string;
+    /**
+     * Timezone name or source
+     */
+    zone: TimezoneSource;
+    /**
+     * Output format
+     */
+    format: TimezoneFormat;
+    /**
+     * Storage format
+     */
+    storeAs: TimezoneStoreAs;
+    /**
+     * Whether to convert on read
+     */
+    convertOnRead: boolean;
+    /**
+     * Whether to convert on write
+     */
+    convertOnWrite: boolean;
+}
+/**
+ * Context for timezone resolution (from request/user)
+ */
+export interface TimezoneContext {
+    /**
+     * User's timezone from request context
+     */
+    timezone?: string;
+    /**
+     * Request object for extracting timezone
+     */
+    request?: any;
+    /**
+     * Additional context data
+     */
+    [key: string]: any;
+}
+/**
+ * Common timezone constants for easy reference
+ */
+export declare const TimezoneEnum: {
+    readonly UTC: "UTC";
+    readonly US_EASTERN: "America/New_York";
+    readonly US_CENTRAL: "America/Chicago";
+    readonly US_MOUNTAIN: "America/Denver";
+    readonly US_PACIFIC: "America/Los_Angeles";
+    readonly EUROPE_LONDON: "Europe/London";
+    readonly EUROPE_PARIS: "Europe/Paris";
+    readonly EUROPE_BERLIN: "Europe/Berlin";
+    readonly ASIA_TOKYO: "Asia/Tokyo";
+    readonly ASIA_SHANGHAI: "Asia/Shanghai";
+    readonly ASIA_SINGAPORE: "Asia/Singapore";
+    readonly AUSTRALIA_SYDNEY: "Australia/Sydney";
+};
+/**
+ * Set timezone context for current request/operation
+ *
+ * @param context - The timezone context
+ */
+export declare function setTimezoneContext(context: TimezoneContext | null): void;
+/**
+ * Get current timezone context
+ *
+ * @returns The current timezone context
+ */
+export declare function getTimezoneContext(): TimezoneContext | null;
+/**
+ * Clear timezone context
+ */
+export declare function clearTimezoneContext(): void;
+/**
+ * Get timezone from context based on source configuration
+ *
+ * @param source - The timezone source configuration
+ * @returns The resolved timezone string
+ */
+export declare function resolveTimezoneFromContext(source: TimezoneSource): string | undefined;
+/**
+ * Get all timezone field metadata from a model class
+ */
+export declare function getTimezoneFields(target: Function): TimezoneFieldMeta[];
+/**
+ * Get timezone metadata for a specific field
+ */
+export declare function getTimezoneForField(target: Function, field: string): TimezoneFieldMeta | undefined;
+/**
+ * Get table-level timezone configuration
+ */
+export declare function getTableTimezone(target: Function): TableTimezoneOptions | undefined;
+/**
+ * Get default timezone from class
+ */
+export declare function getDefaultTimezone(target: Function): string | undefined;
+/**
+ * Convert date to specified timezone
+ *
+ * @param date - The date to convert
+ * @param targetZone - Target timezone (e.g., 'America/New_York')
+ * @returns Date adjusted to target timezone
+ */
+export declare function convertToTimezone(date: Date, targetZone: string): Date;
+/**
+ * Convert date from specified timezone to UTC
+ *
+ * @param date - The date to convert
+ * @param sourceZone - Source timezone (e.g., 'America/New_York')
+ * @returns Date in UTC
+ */
+export declare function convertFromTimezone(date: Date, sourceZone: string): Date;
+/**
+ * Format date according to specified format
+ *
+ * @param date - The date to format
+ * @param format - The format type
+ * @returns Formatted date string or timestamp
+ */
+export declare function formatDateTimezone(date: Date, format: TimezoneFormat): string | number;
+/**
+ * Parse date from database storage format
+ *
+ * @param value - The value from database
+ * @param format - The expected format
+ * @returns Parsed Date object
+ */
+export declare function parseDate(value: any, format: TimezoneFormat): Date | null;
+/**
+ * Convert value when reading from database
+ *
+ * @param value - Raw value from database
+ * @param meta - Timezone metadata
+ * @returns Converted value
+ */
+export declare function convertOnRead(value: any, meta: TimezoneFieldMeta): Date | string | number | null;
+/**
+ * Convert value when writing to database
+ *
+ * @param value - Value from application
+ * @param meta - Timezone metadata
+ * @returns Value ready for database
+ */
+export declare function convertOnWrite(value: any, meta: TimezoneFieldMeta): any;
+/**
+ * Column-level timezone decorator
+ *
+ * @param options - Timezone options or timezone string
+ */
+export declare function Timezone(options?: TimezoneOptions | string): PropertyDecorator;
+/**
+ * Apply timezone conversion to query options
+ *
+ * @param queryOptions - Original query options
+ * @param targetTimezone - Target timezone for conversion
+ * @returns Modified query options with timezone
+ */
+export declare function applyTimezoneToQuery(queryOptions: any, targetTimezone: string): any;
+/**
+ * Convert where clause dates to specified timezone
+ *
+ * @param where - Original where clause
+ * @param timezone - Target timezone
+ * @returns Modified where clause with timezone context
+ */
+export declare function convertWhereToTimezone(where: any, timezone: string): any;
+/**
+ * Get effective timezone for a field (column-level or table-level default)
+ *
+ * @param target - Model class
+ * @param field - Field name
+ * @returns Effective timezone or undefined
+ */
+export declare function getEffectiveTimezone(target: Function, field: string): string | undefined;
+/**
+ * Get all timezone metadata for a model including table defaults
+ *
+ * @param target - Model class
+ * @returns Array of timezone field metadata
+ */
+export declare function getAllTimezoneFields(target: Function): TimezoneFieldMeta[];
+/**
+ * Convert model instance field values based on timezone metadata
+ *
+ * @param instance - Model instance
+ * @param targetTimezone - Target timezone for conversion
+ * @returns Converted instance values
+ */
+export declare function convertInstanceOnRead(instance: any, targetTimezone: string): any;
+/**
+ * Convert model instance field values before writing to database
+ *
+ * @param instance - Model instance
+ * @returns Converted values ready for database
+ */
+export declare function convertInstanceOnWrite(instance: any): any;
+/**
+ * Register hooks for automatic timezone conversion
+ * Call this after Model.init()
+ *
+ * @param ModelClass - The model class
+ */
+export declare function applyTimezoneHooks(ModelClass: any): void;

package/dist/decorators/trigger.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @Trigger class decorator — declare a database trigger on a model class.
+ *
+ * Stores trigger metadata using plain class properties (no reflect-metadata
+ * dependency) consistent with the rest of this decorator suite.
+ *
+ * Example:
+ *
+ *   @Trigger({
+ *     name: 'trg_users_audit',
+ *     timing: 'AFTER',
+ *     event: 'INSERT',
+ *     body: `INSERT INTO audit_log(action, ts) VALUES ('INSERT', NOW())`,
+ *     forEach: 'ROW',
+ *   })
+ *   class User extends Model { ... }
+ *
+ *   // Retrieve trigger definitions:
+ *   const triggers = getTriggers(User);
+ *
+ *   // Generate DDL:
+ *   const sql = buildCreateTriggerSQL('users', triggers[0], 'mysql');
+ */
+export interface TriggerOptions {
+    /** The trigger name in the database. */
+    name: string;
+    /** When the trigger fires relative to the DML event. */
+    timing: 'BEFORE' | 'AFTER' | 'INSTEAD OF';
+    /** The DML event that activates the trigger. */
+    event: 'INSERT' | 'UPDATE' | 'DELETE';
+    /** The SQL body of the trigger action. */
+    body: string;
+    /** Row-level or statement-level (default: 'ROW'). */
+    forEach?: 'ROW' | 'STATEMENT';
+}
+/**
+ * Attach a trigger definition to a model class.
+ * Multiple @Trigger decorators may be stacked on the same class.
+ */
+export declare function Trigger(options: TriggerOptions): ClassDecorator;
+/**
+ * Return all trigger definitions registered on a class.
+ */
+export declare function getTriggers(target: any): TriggerOptions[];
+/**
+ * Generate a CREATE TRIGGER DDL statement for the given dialect.
+ *
+ * Supported dialects: 'mysql' | 'mariadb' | 'postgres' | 'sqlite'
+ */
+export declare function buildCreateTriggerSQL(tableName: string, trigger: TriggerOptions, dialect: string): string;

package/dist/decorators/uuid.d.ts

@@ -0,0 +1,102 @@
+/**
+ * UUID Decorator for the ORM
+ *
+ * Provides PostgreSQL UUID type support with automatic extension management.
+ * Requires: CREATE EXTENSION IF NOT EXISTS "uuid-ossp"
+ *
+ * Usage:
+ *
+ *   // Auto-generate UUID using gen_random_uuid() (PostgreSQL 13+)
+ *   @UUID()
+ *   id: string;
+ *
+ *   // Use uuid_generate_v4() (requires uuid-ossp extension)
+ *   @UUID({ defaultValue: 'uuid_generate_v4' })
+ *   id: string;
+ *
+ *   // With custom default
+ *   @UUID({ defaultValue: 'gen_random_uuid' })
+ *   id: string;
+ */
+/**
+ * Options for UUID column type
+ */
+export interface UUIDDecoratorOptions {
+    /** Default value generator:
+     * - 'gen_random_uuid': Uses gen_random_uuid() (PostgreSQL 13+)
+     * - 'uuid_generate_v4': Uses uuid_generate_v4() (requires uuid-ossp extension)
+     * - Custom SQL expression
+     */
+    defaultValue?: 'gen_random_uuid' | 'uuid_generate_v4' | string;
+    /** Whether the column allows null */
+    allowNull?: boolean;
+    /** Comment for the column */
+    comment?: string;
+    /** Custom column name in the database */
+    field?: string;
+}
+/**
+ * Metadata stored on the property
+ */
+export interface UUIDMetadata {
+    options: UUIDDecoratorOptions;
+}
+/**
+ * UUID decorator for PostgreSQL UUID columns
+ *
+ * @param options - Optional UUID column options
+ *
+ * @example
+ * // Auto-generate UUID
+ * class User extends Model {
+ *   @UUID()
+ *   id: string;
+ * }
+ *
+ * // With specific default
+ * class User extends Model {
+ *   @UUID({ defaultValue: 'uuid_generate_v4' })
+ *   id: string;
+ * }
+ */
+export declare function UUID(options?: UUIDDecoratorOptions): PropertyDecorator;
+/**
+ * Get UUID metadata for a property
+ *
+ * @param target - The target class
+ * @param propertyKey - The property name
+ * @returns UUID metadata or undefined if not found
+ */
+export declare function getUUIDMetadata(target: object, propertyKey: string | symbol): UUIDMetadata | undefined;
+/**
+ * Get all UUID metadata for a class
+ *
+ * @param target - The target class
+ * @returns Map of property names to UUID metadata
+ */
+export declare function getAllUUIDMetadata(target: object): Map<string, UUIDMetadata>;
+/**
+ * Check if a property is a UUID column
+ *
+ * @param target - The target class
+ * @param propertyKey - The property name
+ * @returns True if the property is a UUID column
+ */
+export declare function isUUIDColumn(target: object, propertyKey: string | symbol): boolean;
+/**
+ * Clear UUID metadata (useful for testing)
+ */
+export declare function clearUUIDMetadata(): void;
+/**
+ * Get the SQL to create the UUID extension
+ *
+ * @returns SQL to create the uuid-ossp extension
+ */
+export declare function getUUIDExtensionSQL(): string;
+/**
+ * Build the default value SQL for UUID
+ *
+ * @param options - UUID decorator options
+ * @returns SQL for the default value
+ */
+export declare function buildUUIDDefaultSQL(options: UUIDDecoratorOptions): string | undefined;

package/dist/decorators/view.d.ts

@@ -0,0 +1,213 @@
+/**
+ * @View class decorator — annotate a Model class so it maps to a database view
+ * instead of a base table. The ORM stores the view definition and can generate
+ * the CREATE VIEW DDL for you.
+ *
+ * Example:
+ *
+ *   @View({
+ *     name: 'active_users_view',
+ *     query: `
+ *       SELECT id, name, email, created_at
+ *       FROM users
+ *       WHERE status = 'active'
+ *     `,
+ *     replace: true,
+ *   })
+ *   class ActiveUser extends Model<ActiveUserAttributes> {
+ *     declare id: number;
+ *     declare name: string;
+ *     declare email: string;
+ *     declare createdAt: Date;
+ *   }
+ *
+ *   // After Model.init() — generate and create the view:
+ *   const sql = ViewRegistry.getSQL(ActiveUser);
+ *   await prorm.query(sql);
+ *
+ *   // Or let the ORM create it automatically:
+ *   await ViewRegistry.createView(prorm, ActiveUser);
+ *
+ *   // Query it just like a normal model:
+ *   const users = await ActiveUser.findAll({ where: { name: 'Alice' } });
+ */
+import type { Prorm } from '../prorm';
+export interface ViewOptions {
+    /**
+     * The view name in the database.
+     * Defaults to the class name (snake_cased) if not provided.
+     */
+    name?: string;
+    /**
+     * The SELECT statement that defines the view.
+     * Either `query` or `queryFn` must be provided.
+     */
+    query?: string;
+    /**
+     * A function that returns the SELECT statement.
+     * Useful when the query depends on runtime values or other model table names.
+     */
+    queryFn?: () => string;
+    /**
+     * Optional schema prefix (e.g. 'public' for PostgreSQL).
+     */
+    schema?: string;
+    /**
+     * If true, generates CREATE OR REPLACE VIEW.
+     * Default: false.
+     */
+    replace?: boolean;
+    /**
+     * PostgreSQL only: if true, the view will be marked WITH CHECK OPTION.
+     */
+    checkOption?: boolean | 'CASCADED' | 'LOCAL';
+    /**
+     * Target dialect for DDL generation.
+     * One of: 'mysql' | 'mariadb' | 'postgres' | 'sqlite'
+     * Defaults to 'mysql'.
+     */
+    dialect?: 'mysql' | 'mariadb' | 'postgres' | 'sqlite';
+    /**
+     * PostgreSQL only: if true generates a MATERIALIZED VIEW.
+     */
+    materialized?: boolean;
+}
+/**
+ * Read the @View options attached to a class.
+ * Returns undefined if the class has no @View decorator.
+ */
+export declare function getViewOptions(target: Function): ViewOptions | undefined;
+/**
+ * Mark a Model subclass as a database view.
+ *
+ * - Sets the `tableName` option to the view name so findAll() etc. work correctly.
+ * - Registers view metadata so the ORM can generate CREATE VIEW DDL.
+ *
+ *   @View({ name: 'active_users_view', query: 'SELECT ...' })
+ *   class ActiveUser extends Model { ... }
+ */
+export declare function View(options: ViewOptions): (target: Function) => void;
+export declare const ViewRegistry: {
+    /**
+     * Generate the CREATE VIEW SQL for a @View-annotated class.
+     */
+    getSQL(target: Function, dialectOverride?: ViewOptions["dialect"]): string;
+    /**
+     * Execute the CREATE VIEW statement for a @View-annotated model class.
+     */
+    createView(prorm: Prorm, target: Function, dialectOverride?: ViewOptions["dialect"]): Promise<void>;
+    /**
+     * Drop the view for a @View-annotated class.
+     * @param ifExists - Emit IF EXISTS (default: true)
+     */
+    dropView(prorm: Prorm, target: Function, ifExists?: boolean): Promise<void>;
+};
+export type RefreshStrategy = 'ON DEMAND' | 'ON COMMIT';
+export interface MaterializedViewDecoratorOptions {
+    /**
+     * The materialized view name in the database.
+     * Defaults to the class name (snake_cased) if not provided.
+     */
+    name?: string;
+    /**
+     * The SELECT statement that defines the materialized view.
+     * Either `query` or `queryFn` must be provided.
+     */
+    query?: string;
+    /**
+     * A function that returns the SELECT statement.
+     * Useful when the query depends on runtime values or other model table names.
+     */
+    queryFn?: () => string;
+    /**
+     * Optional schema prefix (e.g. 'public' for PostgreSQL).
+     */
+    schema?: string;
+    /**
+     * If true, uses CREATE OR REPLACE MATERIALIZED VIEW.
+     * Default: false.
+     */
+    replace?: boolean;
+    /**
+     * If true, uses CREATE MATERIALIZED VIEW IF NOT EXISTS.
+     * Default: false.
+     */
+    ifNotExists?: boolean;
+    /**
+     * If false, uses WITH NO DATA (creates view without populating data).
+     * Default: true.
+     */
+    withData?: boolean;
+    /**
+     * Unique index name for CONCURRENTLY refresh support.
+     * If provided, a unique index will be created on the specified column(s).
+     */
+    uniqueIndex?: string;
+    /**
+     * Refresh strategy for the materialized view.
+     * - ON DEMAND: Manual refresh using REFRESH MATERIALIZED VIEW (default)
+     * - ON COMMIT: Auto-refresh on commit (PostgreSQL feature, limited support)
+     */
+    refreshStrategy?: RefreshStrategy;
+    /**
+     * Optional comment for the materialized view.
+     */
+    comment?: string;
+}
+/**
+ * Read the @MaterializedView options attached to a class.
+ * Returns undefined if the class has no @MaterializedView decorator.
+ */
+export declare function getMaterializedViewOptions(target: Function): MaterializedViewDecoratorOptions | undefined;
+/**
+ * Mark a Model subclass as a database materialized view.
+ *
+ * - Sets the `tableName` option to the view name so findAll() etc. work correctly.
+ * - Registers materialized view metadata so the ORM can generate CREATE MATERIALIZED VIEW DDL.
+ * - Adds a `refresh()` static method for refreshing the view data.
+ *
+ *   @MaterializedView({
+ *     name: 'user_stats_view',
+ *     query: `
+ *       SELECT user_id, COUNT(*) as order_count
+ *       FROM orders
+ *       GROUP BY user_id
+ *     `,
+ *     uniqueIndex: 'user_stats_view_user_id_key',
+ *   })
+ *   class UserStats extends Model<UserStatsAttributes> {
+ *     declare userId: number;
+ *     declare orderCount: number;
+ *   }
+ *
+ *   // After Model.init() — generate and create the materialized view:
+ *   const sql = MaterializedViewRegistry.getSQL(UserStats);
+ *   await prorm.query(sql);
+ *
+ *   // Or let the ORM create it automatically:
+ *   await MaterializedViewRegistry.createMaterializedView(prorm, UserStats);
+ *
+ *   // Query it just like a normal model:
+ *   const stats = await UserStats.findAll();
+ *
+ *   // Refresh the materialized view:
+ *   await UserStats.refresh();
+ *   // Or concurrently (requires unique index):
+ *   await UserStats.refresh({ concurrently: true });
+ */
+export declare function MaterializedView(options: MaterializedViewDecoratorOptions): (target: Function) => void;
+export declare const MaterializedViewRegistry: {
+    /**
+     * Generate the CREATE MATERIALIZED VIEW SQL for a @MaterializedView-annotated class.
+     */
+    getSQL(target: Function, dialectOverride?: "postgres"): string;
+    /**
+     * Execute the CREATE MATERIALIZED VIEW statement for a @MaterializedView-annotated model class.
+     */
+    createMaterializedView(prorm: Prorm, target: Function, dialectOverride?: "postgres"): Promise<void>;
+    /**
+     * Drop the materialized view for a @MaterializedView-annotated class.
+     * @param ifExists - Emit IF EXISTS (default: true)
+     */
+    dropMaterializedView(prorm: Prorm, target: Function, ifExists?: boolean): Promise<void>;
+};