ts-prorm-orm 1.1.0 → 1.2.0

package/dist/decorators/default.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Default Value Decorator for the ORM
+ *
+ * Provides a type-safe way to set column defaults without raw SQL.
+ * Supports static values, functions, sequences, and database functions.
+ *
+ * Usage:
+ *
+ *   // Static values
+ *   @Default(18)
+ *   age: number;
+ *
+ *   @Default(true)
+ *   isActive: boolean;
+ *
+ *   @Default('pending')
+ *   status: string;
+ *
+ *   // Function for dynamic default
+ *   @Default(() => new Date())
+ *   createdAt: Date;
+ *
+ *   // Auto-generate UUID
+ *   @Default(() => uuidv4())
+ *   id: string;
+ *
+ *   // For JSON columns
+ *   @Default({ role: 'user', verified: false })
+ *   preferences: object;
+ *
+ *   // For array columns
+ *   @Default(['admin'])
+ *   roles: string[];
+ *
+ *   // Auto-sequences (PostgreSQL)
+ *   @Default({ sequence: 'user_id_seq' })
+ *   id: number;
+ *
+ *   // Database functions
+ *   @Default({ fn: 'now' })
+ *   createdAt: Date;
+ *
+ *   @Default({ fn: 'upper', args: ['username'] })
+ *   username: string;
+ *
+ *   // Raw SQL only when needed
+ *   @Default({ literal: "CURRENT_TIMESTAMP" })
+ *   updatedAt: Date;
+ */
+/**
+ * Options for default value configuration.
+ * Supports multiple ways to specify defaults.
+ */
+export type DefaultValueOptions = DefaultStaticValue | DefaultFunction | DefaultSequence | DefaultDatabaseFn | DefaultLiteral;
+/**
+ * Static value (primitive, object, array).
+ */
+export type DefaultStaticValue = any;
+/**
+ * Function that returns the default value.
+ * Called at runtime when creating new instances.
+ */
+export interface DefaultFunction {
+    fn: (instance?: any) => any;
+}
+/**
+ * Database sequence for auto-increment (PostgreSQL).
+ */
+export interface DefaultSequence {
+    sequence: string;
+}
+/**
+ * Database function call (e.g., NOW(), UPPER(), etc.)
+ */
+export interface DefaultDatabaseFn {
+    fn: string;
+    args?: any[];
+}
+/**
+ * Raw SQL literal (use sparingly).
+ */
+export interface DefaultLiteral {
+    literal: string;
+}
+export interface DefaultFieldMeta {
+    field: string;
+    options: DefaultValueOptions;
+}
+/**
+ * Get all default field metadata from a model class.
+ */
+export declare function getDefaultFields(target: Function): DefaultFieldMeta[];
+/**
+ * Get default value for a specific field.
+ */
+export declare function getDefaultForField(target: Function, field: string): DefaultValueOptions | undefined;
+/**
+ * Convert @Default options to prorm column definition format.
+ * This is used when initializing the model.
+ */
+export declare function toPrormDefault(options: DefaultValueOptions): any;
+/**
+ * Apply default values to a model instance.
+ * Call this in beforeCreate/beforeUpdate hooks.
+ *
+ * @param instance - The model instance
+ */
+export declare function applyDefaultValues(instance: any): void;
+/**
+ * Register beforeCreate hook to automatically apply default values.
+ * Call once per model after Model.init().
+ *
+ * @param ModelClass - The model class
+ */
+export declare function applyDefaultHooks(ModelClass: any): void;
+/**
+ * Set a default value for a model field.
+ *
+ * Can be used as:
+ * - @Default(18) - static value
+ * - @Default(() => new Date()) - function for dynamic defaults
+ * - @Default({ sequence: 'user_id_seq' }) - database sequence
+ * - @Default({ fn: 'now' }) - database function
+ * - @Default({ literal: "CURRENT_TIMESTAMP" }) - raw SQL
+ *
+ * @param options - The default value or configuration
+ */
+export declare function Default(options: DefaultValueOptions): (target: any, propertyKey: string) => void;
+/**
+ * Helper to create a UUID default.
+ * Usage: @Default(() => uuidv4())
+ */
+export declare function uuidDefault(): string;
+/**
+ * Helper to create a current timestamp default.
+ * Usage: @Default(() => new Date())
+ */
+export declare function nowDefault(): Date;
+/**
+ * Helper to create a random integer default.
+ * Usage: @Default(() => Math.floor(Math.random() * 100))
+ */
+export declare function randomIntDefault(min?: number, max?: number): number;
+/**
+ * Helper to create a default based on another field.
+ * Usage: @Default((instance) => instance.username?.toLowerCase())
+ */
+export declare function computedDefault(computeFn: (instance: any) => any): DefaultFunction;

package/dist/decorators/encryption.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Encryption decorators and adapter system for the ORM.
+ *
+ * Allows fields to be annotated with @Secure so values are automatically
+ * hashed before being saved. The encryption algorithm is fully swappable
+ * via EncryptionAdapter — default recommendation is bcrypt, but you can
+ * plug in argon2, scrypt, or any custom implementation.
+ *
+ * Usage:
+ *
+ *   // 1. Install your preferred package, e.g. npm install bcrypt
+ *   // 2. Wire up the adapter once at boot time:
+ *   import bcrypt from 'bcrypt';
+ *   setEncryptionAdapter({
+ *     hash:   (value) => bcrypt.hash(value, 12),
+ *     verify: (plain, hashed) => bcrypt.compare(plain, hashed),
+ *   });
+ *
+ *   // 3. Annotate fields on your model class:
+ *   class User extends Model { ... }
+ *   User.init({
+ *     password: { type: DataTypes.STRING, allowNull: false }
+ *   }, { prorm });
+ *   Secure('password')(User); // field decorator style
+ *
+ *   // Or use the decorator on the class definition (requires experimentalDecorators):
+ *   @SecureField('password')
+ *   class User extends Model { ... }
+ */
+/**
+ * Pluggable encryption adapter.
+ * Implement this interface to use any hashing library.
+ */
+export interface EncryptionAdapter {
+    /**
+     * Hash a plain-text value.
+     * @param value - The plain-text string to hash
+     * @returns A promise that resolves to the hashed string
+     */
+    hash(value: string): Promise<string>;
+    /**
+     * Verify a plain-text value against a previously computed hash.
+     * @param plain  - The plain-text candidate
+     * @param hashed - The stored hash to compare against
+     * @returns A promise resolving to true if they match
+     */
+    verify(plain: string, hashed: string): Promise<boolean>;
+}
+/**
+ * Options for the @Secure / SecureField decorator.
+ */
+export interface SecureOptions {
+    /**
+     * The adapter to use for this specific field.
+     * Overrides the global adapter set via setEncryptionAdapter().
+     */
+    adapter?: EncryptionAdapter;
+    /**
+     * If true, the field will only be hashed when the value has changed
+     * (i.e. it does not look like a hash already). Default: true.
+     */
+    skipIfHashed?: boolean;
+    /**
+     * Optional algorithm label for documentation / metadata purposes.
+     * Has no functional effect — it just marks the intended algorithm.
+     * Example: 'bcrypt', 'argon2id', 'scrypt'
+     */
+    algorithm?: string;
+}
+/**
+ * Set the global encryption adapter used by all @Secure fields that
+ * do not specify their own adapter.
+ *
+ * Call this once during application bootstrap, e.g.:
+ *
+ *   import bcrypt from 'bcrypt';
+ *   setEncryptionAdapter({
+ *     hash:   (v) => bcrypt.hash(v, 12),
+ *     verify: (plain, hash) => bcrypt.compare(plain, hash),
+ *   });
+ */
+export declare function setEncryptionAdapter(adapter: EncryptionAdapter): void;
+/**
+ * Return the currently registered global adapter, or null if none has
+ * been configured.
+ */
+export declare function getEncryptionAdapter(): EncryptionAdapter | null;
+export interface SecureFieldMeta {
+    field: string;
+    options: SecureOptions;
+}
+/**
+ * Read the list of secure-field annotations attached to a model constructor.
+ */
+export declare function getSecureFields(target: Function): SecureFieldMeta[];
+/**
+ * Mark a model field so its value is automatically hashed before INSERT/UPDATE.
+ *
+ * This is a class decorator factory — pass the field name(s):
+ *
+ *   @SecureField('password')
+ *   @SecureField('pin', { algorithm: 'bcrypt', adapter: myAdapter })
+ *   class User extends Model { ... }
+ *
+ * The ORM will call hashSecureFields(instance) in a beforeCreate /
+ * beforeUpdate hook to encrypt the field before it reaches the database.
+ */
+export declare function SecureField(field: string, options?: SecureOptions): (target: Function) => void;
+/**
+ * Alias for SecureField — preferred shorthand.
+ *
+ *   @Secure('password')
+ *   class User extends Model { ... }
+ */
+export declare const Secure: typeof SecureField;
+/**
+ * Hash all @Secure-annotated fields on a model instance.
+ *
+ * Call this inside a beforeCreate / beforeUpdate hook, or let the ORM
+ * do it automatically when you use applySecureHooks().
+ *
+ * @param instance - The model instance whose fields should be hashed
+ */
+export declare function hashSecureFields(instance: any): Promise<void>;
+/**
+ * Verify a plain-text value against the stored hash of a @Secure field.
+ *
+ * @param instance  - The model instance containing the stored hash
+ * @param field     - The field name
+ * @param plainText - The candidate value to check
+ * @returns true if the plain-text matches the stored hash
+ */
+export declare function verifySecureField(instance: any, field: string, plainText: string): Promise<boolean>;
+/**
+ * Register beforeCreate and beforeUpdate hooks on a model so that
+ * @Secure fields are automatically hashed whenever an instance is saved.
+ *
+ * Call once per model after Model.init():
+ *
+ *   applySecureHooks(User);
+ *
+ * @param ModelClass - The model class (result of prorm.define or Model.init)
+ */
+export declare function applySecureHooks(ModelClass: any): void;
+/**
+ * Create a bcrypt adapter.
+ *
+ * Requires `bcrypt` or `bcryptjs` to be installed:
+ *   npm install bcrypt       (native, faster)
+ *   npm install bcryptjs     (pure JS, no native build)
+ *
+ * @param saltRounds - bcrypt cost factor (default: 12)
+ *
+ * Usage:
+ *   import bcrypt from 'bcrypt';
+ *   setEncryptionAdapter(createBcryptAdapter(bcrypt, 12));
+ */
+export declare function createBcryptAdapter(bcryptLib: {
+    hash(data: string, saltOrRounds: number): Promise<string>;
+    compare(data: string, encrypted: string): Promise<boolean>;
+}, saltRounds?: number): EncryptionAdapter;
+/**
+ * Create an argon2 adapter.
+ *
+ * Requires `argon2` to be installed:
+ *   npm install argon2
+ *
+ * Usage:
+ *   import argon2 from 'argon2';
+ *   setEncryptionAdapter(createArgon2Adapter(argon2));
+ */
+export declare function createArgon2Adapter(argon2Lib: {
+    hash(plain: string): Promise<string>;
+    verify(hash: string, plain: string): Promise<boolean>;
+}): EncryptionAdapter;

package/dist/decorators/engine.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `@Engine` — class decorator for annotating a Model with dialect-specific
+ * per-table storage-engine configuration, mirroring the `@View`/
+ * `@MaterializedView` pattern (`src/decorators/view.ts`): stores metadata on
+ * the class, exposed via a registry, rather than being silently read by
+ * `Prorm.sync()` - keeping engine selection an explicit, visible step.
+ *
+ * Built for ClickHouse's MergeTree-family engine configuration first (the
+ * dialect that most needs per-table engine choice - `mergeTreeEngine`/
+ * `orderBy`/`ttl`/`partitionBy`/`projections` are all read as loosely-typed
+ * extensions off `TableOptions` in `src/dialects/clickhouse/index.ts` since
+ * the base `Dialect` interface has no notion of storage engines), but the
+ * shape is generic enough for any dialect with similar per-table engine/
+ * storage options (e.g. MySQL's `ENGINE=InnoDB`).
+ *
+ * Example:
+ *
+ *   @Engine({
+ *     mergeTreeEngine: { type: 'ReplacingMergeTree', version: 'updatedAt' },
+ *     orderBy: ['id', 'createdAt'],
+ *     ttl: 'createdAt + INTERVAL 90 DAY',
+ *   })
+ *   class Event extends Model {
+ *     declare id: number;
+ *     declare createdAt: Date;
+ *     declare updatedAt: Date;
+ *   }
+ *
+ *   // At table-creation time:
+ *   const dialect = prorm.getDialectInstance() as ClickHouseDialect;
+ *   await dialect.createTable('events', columns, {
+ *     ...EngineRegistry.getTableOptions(Event),
+ *   });
+ */
+import type { MergeTreeEngineConfig, ProjectionDefinition } from '../dialects/clickhouse';
+export interface EngineOptions {
+    /**
+     * MySQL/MariaDB-style raw engine name, e.g. 'InnoDB', 'MyISAM'.
+     * Ignored by dialects that use `mergeTreeEngine` instead (ClickHouse).
+     */
+    engine?: string;
+    /**
+     * ClickHouse MergeTree-family engine configuration (see
+     * `MergeTreeEngineConfig` in `src/dialects/clickhouse/index.ts`). Takes
+     * precedence over `engine` when both are supplied, since it gets the
+     * engine's required-column validation (e.g. CollapsingMergeTree's
+     * `Sign Int8` column) a raw engine string cannot.
+     */
+    mergeTreeEngine?: MergeTreeEngineConfig;
+    /**
+     * ClickHouse ORDER BY clause (mandatory for MergeTree-family engines -
+     * ClickHouse's stand-in for a traditional primary key, controlling
+     * physical sort/merge order). Either a raw SQL fragment or a column list.
+     */
+    orderBy?: string | string[];
+    /** ClickHouse PARTITION BY clause. */
+    partitionBy?: string;
+    /**
+     * ClickHouse table-level TTL expression, e.g.
+     * `'createdAt + INTERVAL 30 DAY'` or
+     * `"createdAt + INTERVAL 30 DAY TO VOLUME 'cold'"`.
+     */
+    ttl?: string;
+    /**
+     * ClickHouse MergeTree projections to create inline at CREATE TABLE time,
+     * keyed by projection name.
+     */
+    projections?: Record<string, ProjectionDefinition>;
+}
+/**
+ * Read the @Engine options attached to a class.
+ * Returns undefined if the class has no @Engine decorator.
+ */
+export declare function getEngineOptions(target: Function): EngineOptions | undefined;
+/**
+ * Annotate a Model subclass with dialect-specific storage-engine
+ * configuration.
+ *
+ *   @Engine({ mergeTreeEngine: { type: 'AggregatingMergeTree' }, orderBy: ['id'] })
+ *   class Metrics extends Model { ... }
+ */
+export declare function Engine(options: EngineOptions): (target: Function) => void;
+export declare const EngineRegistry: {
+    /**
+     * Read the raw @Engine options attached to a class.
+     */
+    getOptions(target: Function): EngineOptions | undefined;
+    /**
+     * Returns the @Engine options in the shape `createTable()` expects to be
+     * spread into its `options` argument (ClickHouse reads `mergeTreeEngine`/
+     * `orderBy`/`ttl`/`partitionBy`/`projections` as loosely-typed extensions;
+     * MySQL/MariaDB read `engine` directly off `TableOptions`). Returns an
+     * empty object (not undefined) when the class has no @Engine decorator,
+     * so callers can always safely spread the result.
+     */
+    getTableOptions(target: Function): Record<string, unknown>;
+};