ts-prorm-orm 1.1.0

package/dist/decorators/permissions.js

@@ -0,0 +1,294 @@
+"use strict";
+/**
+ * Permission / access-control decorators for the ORM.
+ *
+ * These decorators let you annotate model classes and individual fields with
+ * access rules — which roles can read, write, or are completely blocked from
+ * a field or an entire model. At query time you call filterByPermissions()
+ * to strip out any fields the current user is not allowed to see.
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * Quick Reference
+ * ──────────────────────────────────────────────────────────────────────────
+ *
+ *  @CanView('admin', 'manager')     — only these roles can read the field/model
+ *  @CannotView('guest')             — these roles are DENIED read access
+ *  @CanWrite('admin')               — only these roles can write the field
+ *  @CannotWrite('guest')            — these roles are DENIED write access
+ *  @Permission({ ... })             — full control with explicit allow/deny lists
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * Example
+ * ──────────────────────────────────────────────────────────────────────────
+ *
+ *   // Field-level permissions (applied via static registration):
+ *   PermissionRegistry.addFieldRule(User, 'ssn',      { canView: ['admin'] });
+ *   PermissionRegistry.addFieldRule(User, 'salary',   { canView: ['admin', 'hr'] });
+ *   PermissionRegistry.addFieldRule(User, 'password', { canView: [] });  // nobody
+ *
+ *   // Class-level permission (applied via decorator):
+ *   @CanView('admin', 'manager')
+ *   class AuditLog extends Model { ... }
+ *
+ *   // At request time:
+ *   const currentRole = 'guest';
+ *   const user = await User.findOne({ where: { id: 1 } });
+ *   const safeUser = filterByPermissions(user, currentRole);
+ *   // safeUser.ssn === undefined, safeUser.salary === undefined
+ *
+ *   // Or get the allowed attribute list for a findAll() call:
+ *   const attrs = getAllowedAttributes(User, currentRole);
+ *   const users = await User.findAll({ attributes: attrs });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionRegistry = void 0;
+exports.canViewField = canViewField;
+exports.canWriteField = canWriteField;
+exports.getAllowedAttributes = getAllowedAttributes;
+exports.filterByPermissions = filterByPermissions;
+exports.filterWriteByPermissions = filterWriteByPermissions;
+exports.CanView = CanView;
+exports.CannotView = CannotView;
+exports.CanWrite = CanWrite;
+exports.CannotWrite = CannotWrite;
+exports.Permission = Permission;
+exports.withPermissions = withPermissions;
+// ==================== Registry ====================
+// model constructor → field name → rule
+const fieldRules = new Map();
+// model constructor → model-level rule
+const modelRules = new Map();
+function getFieldMap(target) {
+    if (!fieldRules.has(target))
+        fieldRules.set(target, new Map());
+    return fieldRules.get(target);
+}
+exports.PermissionRegistry = {
+    // ── Field-level rules ──────────────────────────────────────────────────
+    /**
+     * Register or update a permission rule for a specific field on a model.
+     *
+     * @param target    - The model class constructor
+     * @param fieldName - The attribute/field name
+     * @param rule      - The access rule
+     */
+    addFieldRule(target, fieldName, rule) {
+        const map = getFieldMap(target);
+        const existing = map.get(fieldName) ?? {};
+        map.set(fieldName, { ...existing, ...rule });
+    },
+    /**
+     * Get the rule for a specific field (or undefined if none).
+     */
+    getFieldRule(target, fieldName) {
+        return getFieldMap(target).get(fieldName);
+    },
+    /**
+     * Get all field rules registered on a model.
+     */
+    getAllFieldRules(target) {
+        return getFieldMap(target);
+    },
+    // ── Model-level rules ──────────────────────────────────────────────────
+    /**
+     * Register or update a model-level permission rule (applies to ALL fields).
+     */
+    addModelRule(target, rule) {
+        const existing = modelRules.get(target) ?? {};
+        modelRules.set(target, { ...existing, ...rule });
+    },
+    /**
+     * Get the model-level rule (or undefined if none).
+     */
+    getModelRule(target) {
+        return modelRules.get(target);
+    },
+};
+// ==================== Access-Check Helpers ====================
+/**
+ * Check whether a given role can VIEW a field on a model.
+ *
+ * Resolution order:
+ *   1. Field-level cannotView  → deny if role is listed
+ *   2. Field-level canView     → allow only if role is listed (or '*' present)
+ *   3. Model-level cannotView  → deny if role is listed
+ *   4. Model-level canView     → allow only if role is listed (or '*' present)
+ *   5. Default: allow
+ *
+ * @param ModelClass - The model constructor
+ * @param fieldName  - The attribute name to check
+ * @param role       - The current user's role
+ */
+function canViewField(ModelClass, fieldName, role) {
+    const fieldRule = exports.PermissionRegistry.getFieldRule(ModelClass, fieldName);
+    const modelRule = exports.PermissionRegistry.getModelRule(ModelClass);
+    // Field-level cannotView
+    if (fieldRule?.cannotView?.includes(role))
+        return false;
+    // Field-level canView
+    if (fieldRule?.canView !== undefined) {
+        return fieldRule.canView.includes('*') || fieldRule.canView.includes(role);
+    }
+    // Model-level cannotView
+    if (modelRule?.cannotView?.includes(role))
+        return false;
+    // Model-level canView
+    if (modelRule?.canView !== undefined) {
+        return modelRule.canView.includes('*') || modelRule.canView.includes(role);
+    }
+    return true; // default: allow
+}
+/**
+ * Check whether a given role can WRITE a field on a model.
+ */
+function canWriteField(ModelClass, fieldName, role) {
+    const fieldRule = exports.PermissionRegistry.getFieldRule(ModelClass, fieldName);
+    const modelRule = exports.PermissionRegistry.getModelRule(ModelClass);
+    if (fieldRule?.cannotWrite?.includes(role))
+        return false;
+    if (fieldRule?.canWrite !== undefined) {
+        return fieldRule.canWrite.includes('*') || fieldRule.canWrite.includes(role);
+    }
+    if (modelRule?.cannotWrite?.includes(role))
+        return false;
+    if (modelRule?.canWrite !== undefined) {
+        return modelRule.canWrite.includes('*') || modelRule.canWrite.includes(role);
+    }
+    return true;
+}
+// ==================== Attribute Filtering ====================
+/**
+ * Return the list of field names on a model that `role` is allowed to VIEW.
+ *
+ * Useful for passing to `findAll({ attributes: ... })` to prevent loading
+ * restricted data at the database level.
+ *
+ * @param ModelClass      - The model constructor
+ * @param role            - The current user's role
+ * @param allAttributes   - The full list of attribute names. If omitted,
+ *                          the registry's field rules are used as the universe
+ *                          (only fields with explicit rules are considered).
+ */
+function getAllowedAttributes(ModelClass, role, allAttributes) {
+    const fields = allAttributes ?? Array.from(exports.PermissionRegistry.getAllFieldRules(ModelClass).keys());
+    return fields.filter((f) => canViewField(ModelClass, f, role));
+}
+/**
+ * Strip restricted fields from a plain object or model instance.
+ *
+ * Returns a new plain object with only the fields `role` is allowed to see.
+ * Does not mutate the original.
+ *
+ * @param instance   - A model instance or plain record object
+ * @param role       - The current user's role
+ * @param ModelClass - The model class (defaults to instance.constructor)
+ */
+function filterByPermissions(instance, role, ModelClass) {
+    const Model = ModelClass ?? instance.constructor;
+    // Get the plain data object
+    const data = typeof instance.toJSON === 'function' ? instance.toJSON() : { ...instance };
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (canViewField(Model, key, role)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Strip restricted fields from a plain object for WRITE operations.
+ * Removes any fields the role is not allowed to write.
+ */
+function filterWriteByPermissions(data, role, ModelClass) {
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (canWriteField(ModelClass, key, role)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+// ==================== Decorators ====================
+/**
+ * Allow only the listed roles to VIEW the decorated class (all fields) or
+ * use PermissionRegistry.addFieldRule() for per-field control.
+ *
+ *   @CanView('admin', 'manager')
+ *   class AuditLog extends Model { ... }
+ */
+function CanView(...roles) {
+    return function (target) {
+        exports.PermissionRegistry.addModelRule(target, { canView: roles });
+    };
+}
+/**
+ * Deny the listed roles from viewing the decorated class.
+ *
+ *   @CannotView('guest', 'public')
+ *   class SensitiveReport extends Model { ... }
+ */
+function CannotView(...roles) {
+    return function (target) {
+        exports.PermissionRegistry.addModelRule(target, { cannotView: roles });
+    };
+}
+/**
+ * Allow only the listed roles to WRITE to the decorated class.
+ *
+ *   @CanWrite('admin')
+ *   class Settings extends Model { ... }
+ */
+function CanWrite(...roles) {
+    return function (target) {
+        exports.PermissionRegistry.addModelRule(target, { canWrite: roles });
+    };
+}
+/**
+ * Deny the listed roles from writing to the decorated class.
+ */
+function CannotWrite(...roles) {
+    return function (target) {
+        exports.PermissionRegistry.addModelRule(target, { cannotWrite: roles });
+    };
+}
+/**
+ * Full permission decorator — applies read and write rules at the model level.
+ *
+ *   @Permission({ canView: ['admin', 'manager'], canWrite: ['admin'] })
+ *   class Invoice extends Model { ... }
+ */
+function Permission(options) {
+    return function (target) {
+        exports.PermissionRegistry.addModelRule(target, options);
+    };
+}
+// ==================== Controller-Style Helpers ====================
+/**
+ * A higher-order helper that wraps a controller function and automatically
+ * applies permission filtering on the result.
+ *
+ * Example:
+ *
+ *   const getUser = withPermissions(User, async (id: number) => {
+ *     return User.findByPk(id);
+ *   });
+ *
+ *   const safeUser = await getUser(1, 'guest');
+ *   // safeUser has only the fields 'guest' is allowed to see
+ *
+ * @param ModelClass - The model class whose permissions to apply
+ * @param fn         - The async controller function (last arg must be role string)
+ */
+function withPermissions(ModelClass, fn) {
+    return async (...args) => {
+        const role = args[args.length - 1];
+        const fnArgs = args.slice(0, -1);
+        const result = await fn(...fnArgs);
+        if (!result)
+            return null;
+        if (Array.isArray(result)) {
+            return result.map((item) => filterByPermissions(item, role, ModelClass));
+        }
+        return filterByPermissions(result, role, ModelClass);
+    };
+}

package/dist/decorators/procedure.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * TypeScript decorators for SQL Stored Procedures and SQL Functions.
+ *
+ * @Procedure  — annotate a class method (or standalone function wrapper) so
+ *               it is understood by the ORM as a stored procedure.
+ *               The ORM can generate the CREATE PROCEDURE SQL and register
+ *               a callable wrapper on your Prorm instance.
+ *
+ * @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.
+ *
+ * Example:
+ *
+ *   class UserProcedures {
+ *     @Procedure({
+ *       name: 'get_user_by_email',
+ *       params: [{ name: 'p_email', type: 'VARCHAR(255)', mode: 'IN' }],
+ *       dialect: 'mysql',
+ *       body: `BEGIN SELECT * FROM users WHERE email = p_email; END`,
+ *     })
+ *     getUserByEmail(email: string) {}
+ *
+ *     @SqlFunction({
+ *       name: 'full_name',
+ *       params: [
+ *         { name: 'first', type: 'TEXT' },
+ *         { name: 'last',  type: 'TEXT' },
+ *       ],
+ *       returns: 'TEXT',
+ *       dialect: 'postgres',
+ *       body: `SELECT first || ' ' || last`,
+ *       language: 'SQL',
+ *     })
+ *     fullName(first: string, last: string): string { return ''; }
+ *   }
+ *
+ *   // Generate and run the DDL
+ *   const sql = ProcedureRegistry.getSQL(UserProcedures, 'getUserByEmail');
+ *   await prorm.query(sql);
+ *
+ *   // Or use the auto-call helper
+ *   const rows = await ProcedureRegistry.call(prorm, UserProcedures, 'getUserByEmail', ['john@example.com']);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProcedureRegistry = void 0;
+exports.Procedure = Procedure;
+exports.SqlFunction = SqlFunction;
+const registry = new Map();
+function getOrCreateMap(target) {
+    if (!registry.has(target))
+        registry.set(target, new Map());
+    return registry.get(target);
+}
+// ==================== Decorators ====================
+/**
+ * Mark a method as a SQL stored procedure.
+ *
+ * The decorated method is a no-op at runtime — use ProcedureRegistry.call()
+ * to execute the actual database procedure.
+ */
+function Procedure(options = {}) {
+    return function (target, propertyKey, _descriptor) {
+        const map = getOrCreateMap(target.constructor ?? target);
+        map.set(propertyKey, {
+            kind: 'procedure',
+            methodKey: propertyKey,
+            options: { name: propertyKey, ...options },
+        });
+    };
+}
+/**
+ * Mark a method as a SQL function (returns a value, usable in SELECT/WHERE).
+ *
+ * The decorated method is a no-op at runtime — use ProcedureRegistry.call()
+ * to execute the actual database function.
+ */
+function SqlFunction(options) {
+    return function (target, propertyKey, _descriptor) {
+        const map = getOrCreateMap(target.constructor ?? target);
+        map.set(propertyKey, {
+            kind: 'function',
+            methodKey: propertyKey,
+            options: { name: propertyKey, ...options },
+        });
+    };
+}
+// ==================== SQL Generation ====================
+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';
+    return `${drop}CREATE PROCEDURE ${name}(${params})\nBEGIN\n  ${body}\nEND`;
+}
+function buildMysqlFunction(meta) {
+    const opts = meta.options;
+    const name = opts.schema ? `\`${opts.schema}\`.\`${opts.name}\`` : `\`${opts.name}\``;
+    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';
+    return `${drop}CREATE FUNCTION ${name}(${params})\nRETURNS ${opts.returns}\n${determinism}\nBEGIN\n  ${body}\nEND`;
+}
+function buildPostgresProcedure(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 orReplace = opts.replace ? 'OR REPLACE ' : '';
+    const body = opts.body ?? '-- TODO: add procedure body here';
+    return `CREATE ${orReplace}PROCEDURE ${name}(${params})\nLANGUAGE plpgsql\nAS $$\nBEGIN\n  ${body}\nEND;\n$$`;
+}
+function buildPostgresFunction(meta) {
+    const opts = meta.options;
+    const name = opts.schema ? `"${opts.schema}"."${opts.name}"` : `"${opts.name}"`;
+    const params = (opts.params ?? []).map((p) => `${p.name} ${p.type}`).join(', ');
+    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 bodyWrapper = language === 'SQL' ? `$$ ${body} $$` : `$$\nBEGIN\n  ${body}\nEND;\n$$`;
+    return `CREATE ${orReplace}FUNCTION ${name}(${params})\nRETURNS ${opts.returns}${volatility}\nLANGUAGE ${language}\nAS ${bodyWrapper}`;
+}
+// ==================== Public Registry API ====================
+exports.ProcedureRegistry = {
+    /**
+     * Get all registered procedures/functions on a class.
+     */
+    getAll(target) {
+        return Array.from(getOrCreateMap(target).values());
+    },
+    /**
+     * Get a single procedure/function meta by method name.
+     */
+    get(target, methodKey) {
+        return getOrCreateMap(target).get(methodKey);
+    },
+    /**
+     * Generate the CREATE PROCEDURE / CREATE FUNCTION SQL for a registered method.
+     *
+     * @param target    - The class constructor
+     * @param methodKey - The method name
+     * @param dialect   - Override the dialect stored in the decorator options
+     */
+    getSQL(target, methodKey, dialect) {
+        const meta = getOrCreateMap(target).get(methodKey);
+        if (!meta)
+            throw new Error(`[ORM] No @Procedure/@SqlFunction found for method "${methodKey}"`);
+        const effectiveDialect = dialect ?? meta.options.dialect ?? 'mysql';
+        if (meta.kind === 'procedure') {
+            if (effectiveDialect === 'postgres')
+                return buildPostgresProcedure(meta);
+            return buildMysqlProcedure(meta); // mysql / mariadb
+        }
+        else {
+            if (effectiveDialect === 'postgres')
+                return buildPostgresFunction(meta);
+            return buildMysqlFunction(meta);
+        }
+    },
+    /**
+     * Generate DDL for every procedure/function on a class and execute them.
+     *
+     * @param prorm - Prorm instance
+     * @param target    - The class constructor
+     * @param dialect   - Override dialect
+     */
+    async createAll(prorm, target, dialect) {
+        for (const [methodKey] of getOrCreateMap(target)) {
+            const sql = exports.ProcedureRegistry.getSQL(target, methodKey, dialect);
+            await prorm.query(sql);
+        }
+    },
+    /**
+     * Call a stored procedure.
+     *
+     * @param prorm - Prorm instance
+     * @param target    - The class constructor that has the @Procedure decorator
+     * @param methodKey - The method name
+     * @param args      - Arguments to pass (positional, matched to params order)
+     */
+    async call(prorm, target, methodKey, args = []) {
+        const meta = getOrCreateMap(target).get(methodKey);
+        if (!meta)
+            throw new Error(`[ORM] No @Procedure found for method "${methodKey}"`);
+        const opts = meta.options;
+        const name = opts.name ?? methodKey;
+        const dialect = opts.dialect ?? 'mysql';
+        const placeholders = args.map(() => (dialect === 'postgres' ? '$?' : '?')).join(', ');
+        let sql;
+        if (meta.kind === 'procedure') {
+            sql =
+                dialect === 'mysql' || dialect === 'mariadb'
+                    ? `CALL \`${name}\`(${placeholders})`
+                    : `CALL "${name}"(${placeholders})`;
+        }
+        else {
+            sql =
+                dialect === 'postgres'
+                    ? `SELECT * FROM "${name}"(${placeholders})`
+                    : `SELECT ${name}(${placeholders})`;
+        }
+        return prorm.query(sql, { replacements: args });
+    },
+};