ts-prorm-orm 1.1.0

package/dist/decorators/encryption.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * 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 { ... }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Secure = void 0;
+exports.setEncryptionAdapter = setEncryptionAdapter;
+exports.getEncryptionAdapter = getEncryptionAdapter;
+exports.getSecureFields = getSecureFields;
+exports.SecureField = SecureField;
+exports.hashSecureFields = hashSecureFields;
+exports.verifySecureField = verifySecureField;
+exports.applySecureHooks = applySecureHooks;
+exports.createBcryptAdapter = createBcryptAdapter;
+exports.createArgon2Adapter = createArgon2Adapter;
+// ==================== Global Registry ====================
+let globalAdapter = null;
+/**
+ * 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),
+ *   });
+ */
+function setEncryptionAdapter(adapter) {
+    globalAdapter = adapter;
+}
+/**
+ * Return the currently registered global adapter, or null if none has
+ * been configured.
+ */
+function getEncryptionAdapter() {
+    return globalAdapter;
+}
+// ==================== Field Metadata ====================
+const SECURE_FIELDS_KEY = '__orm_secure_fields__';
+/**
+ * Read the list of secure-field annotations attached to a model constructor.
+ */
+function getSecureFields(target) {
+    return target[SECURE_FIELDS_KEY] || [];
+}
+// ==================== Decorators ====================
+/**
+ * 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.
+ */
+function SecureField(field, options = {}) {
+    return function (target) {
+        if (!target[SECURE_FIELDS_KEY]) {
+            target[SECURE_FIELDS_KEY] = [];
+        }
+        target[SECURE_FIELDS_KEY].push({ field, options });
+    };
+}
+/**
+ * Alias for SecureField — preferred shorthand.
+ *
+ *   @Secure('password')
+ *   class User extends Model { ... }
+ */
+exports.Secure = SecureField;
+// ==================== Runtime Helpers ====================
+/**
+ * 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
+ */
+async function hashSecureFields(instance) {
+    const ModelClass = instance.constructor;
+    const secureFields = getSecureFields(ModelClass);
+    for (const { field, options } of secureFields) {
+        const value = instance.getDataValue
+            ? instance.getDataValue(field)
+            : instance[field];
+        if (value == null || typeof value !== 'string')
+            continue;
+        // Skip if the value already looks like a hash (starts with $2b$, $argon2, etc.)
+        const skipIfHashed = options.skipIfHashed !== false; // default true
+        if (skipIfHashed && looksLikeHash(value))
+            continue;
+        const adapter = options.adapter ?? globalAdapter;
+        if (!adapter) {
+            throw new Error(`[ORM] No encryption adapter configured for field "${field}". ` +
+                `Call setEncryptionAdapter() at boot time, or provide an adapter in @Secure options.`);
+        }
+        const hashed = await adapter.hash(value);
+        if (instance.setDataValue) {
+            instance.setDataValue(field, hashed);
+        }
+        else {
+            instance[field] = hashed;
+        }
+    }
+}
+/**
+ * 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
+ */
+async function verifySecureField(instance, field, plainText) {
+    const ModelClass = instance.constructor;
+    const secureFields = getSecureFields(ModelClass);
+    const meta = secureFields.find((m) => m.field === field);
+    const adapter = meta?.options.adapter ?? globalAdapter;
+    if (!adapter) {
+        throw new Error(`[ORM] No encryption adapter configured for field "${field}". ` +
+            `Call setEncryptionAdapter() at boot time.`);
+    }
+    const stored = instance.getDataValue
+        ? instance.getDataValue(field)
+        : instance[field];
+    if (!stored)
+        return false;
+    return adapter.verify(plainText, stored);
+}
+/**
+ * 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)
+ */
+function applySecureHooks(ModelClass) {
+    const fields = getSecureFields(ModelClass);
+    if (fields.length === 0)
+        return;
+    // Register hooks via the ORM's addHook API
+    if (typeof ModelClass.addHook === 'function') {
+        ModelClass.addHook('beforeCreate', 'orm:secureHash', async (instance) => {
+            await hashSecureFields(instance);
+        });
+        ModelClass.addHook('beforeUpdate', 'orm:secureHash', async (instance) => {
+            await hashSecureFields(instance);
+        });
+        ModelClass.addHook('beforeSave', 'orm:secureHash', async (instance) => {
+            await hashSecureFields(instance);
+        });
+    }
+}
+// ==================== Convenience Adapters ====================
+/**
+ * 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));
+ */
+function createBcryptAdapter(bcryptLib, saltRounds = 12) {
+    return {
+        hash: (value) => bcryptLib.hash(value, saltRounds),
+        verify: (plain, hashed) => bcryptLib.compare(plain, hashed),
+    };
+}
+/**
+ * Create an argon2 adapter.
+ *
+ * Requires `argon2` to be installed:
+ *   npm install argon2
+ *
+ * Usage:
+ *   import argon2 from 'argon2';
+ *   setEncryptionAdapter(createArgon2Adapter(argon2));
+ */
+function createArgon2Adapter(argon2Lib) {
+    return {
+        hash: (value) => argon2Lib.hash(value),
+        verify: (plain, hashed) => argon2Lib.verify(hashed, plain),
+    };
+}
+// ==================== Internal Helpers ====================
+/**
+ * Heuristic check — does this string look like an already-computed hash?
+ * Supports bcrypt ($2a$, $2b$, $2y$), argon2 ($argon2), and scrypt ($scrypt).
+ */
+function looksLikeHash(value) {
+    return (/^\$2[aby]\$/.test(value) || // bcrypt
+        /^\$argon2/.test(value) || // argon2
+        /^\$scrypt\$/.test(value) // scrypt (node-scrypt-format)
+    );
+}

package/dist/decorators/engine.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * `@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),
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EngineRegistry = void 0;
+exports.getEngineOptions = getEngineOptions;
+exports.Engine = Engine;
+// ==================== Registry ====================
+const ENGINE_OPTIONS_KEY = '__orm_engine_options__';
+/**
+ * Read the @Engine options attached to a class.
+ * Returns undefined if the class has no @Engine decorator.
+ */
+function getEngineOptions(target) {
+    return target[ENGINE_OPTIONS_KEY];
+}
+// ==================== Decorator ====================
+/**
+ * Annotate a Model subclass with dialect-specific storage-engine
+ * configuration.
+ *
+ *   @Engine({ mergeTreeEngine: { type: 'AggregatingMergeTree' }, orderBy: ['id'] })
+ *   class Metrics extends Model { ... }
+ */
+function Engine(options) {
+    return function (target) {
+        target[ENGINE_OPTIONS_KEY] = { ...options };
+    };
+}
+// ==================== Public Registry API ====================
+exports.EngineRegistry = {
+    /**
+     * Read the raw @Engine options attached to a class.
+     */
+    getOptions(target) {
+        return getEngineOptions(target);
+    },
+    /**
+     * 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) {
+        const opts = getEngineOptions(target);
+        if (!opts)
+            return {};
+        const tableOptions = {};
+        if (opts.engine !== undefined)
+            tableOptions.engine = opts.engine;
+        if (opts.mergeTreeEngine !== undefined)
+            tableOptions.mergeTreeEngine = opts.mergeTreeEngine;
+        if (opts.orderBy !== undefined)
+            tableOptions.orderBy = opts.orderBy;
+        if (opts.partitionBy !== undefined)
+            tableOptions.partitionBy = opts.partitionBy;
+        if (opts.ttl !== undefined)
+            tableOptions.ttl = opts.ttl;
+        if (opts.projections !== undefined)
+            tableOptions.projections = opts.projections;
+        return tableOptions;
+    },
+};