ts-prorm-orm 1.1.0 → 1.2.1

package/dist/compliance/data-lineage.d.ts

@@ -0,0 +1,268 @@
+/**
+ * DataLineage
+ *
+ * Tracks data origin, transformation history, and provenance chain for records.
+ * Enables compliance with BCBS 239, GDPR Art 30, HIPAA, and SOX requirements
+ * for data lineage and auditability.
+ *
+ * Covers ~45 compliance frameworks including:
+ *   BCBS 239, GDPR Art 25/30/32, HIPAA, SOX, SOC 2, ISO 27001,
+ *   NIST SP 800-53, PCI DSS, FINRA, and data lineage requirements.
+ *
+ * Usage:
+ *   // Enable lineage tracking on a model:
+ *   DataLineage.enable(Order, prorm, { tableName: 'OrderLineage' });
+ *
+ *   // Track a data source:
+ *   await DataLineage.trackSource(Order, 'import', { source: 'csv_upload', importedAt: new Date() });
+ *
+ *   // Get full lineage chain:
+ *   const lineage = await DataLineage.getLineage(orderId, 'Orders');
+ *
+ *   // Get just the origin:
+ *   const provenance = await DataLineage.getProvenance(orderId, 'Orders');
+ *
+ *   // Get transformation history:
+ *   const transforms = await DataLineage.getTransformations(orderId, 'Orders');
+ *
+ *   // Using the decorator:
+ *   @LineageTrack({ fields: ['amount', 'total'] })
+ *   class Order extends Model { ... }
+ */
+import { ModelStatic, Prorm } from '../prorm';
+/** The origin of data - how it entered the system */
+export type DataSource = 
+/** Data imported from external systems (ETL, CSV, API sync) */
+'import'
+/** Data entered directly by a user */
+ | 'user_input'
+/** Data computed from other values (calculated fields) */
+ | 'computed'
+/** Data derived from other records (aggregates, rollups) */
+ | 'derived';
+/** A transformation operation applied to a record */
+export interface TransformationRecord {
+    /** Unique identifier for this transformation */
+    id: number;
+    /** Record ID this transformation applies to */
+    recordId: string | number;
+    /** Table name */
+    tableName: string;
+    /** Type of transformation */
+    operation: string;
+    /** Description of what was done */
+    description?: string;
+    /** User who performed the transformation */
+    performedBy?: string | number;
+    /** When the transformation occurred */
+    timestamp: Date;
+    /** Input values before transformation */
+    inputValues?: Record<string, any>;
+    /** Output values after transformation */
+    outputValues?: Record<string, any>;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+/** A single lineage record tracking data origin */
+export interface LineageRecord {
+    /** Unique identifier */
+    id: number;
+    /** Record ID this lineage applies to */
+    recordId: string | number;
+    /** Table name */
+    tableName: string;
+    /** Original data source */
+    source: DataSource;
+    /** Source system or origin details */
+    sourceDetails?: string;
+    /** Additional metadata about the origin */
+    originMetadata?: Record<string, any>;
+    /** ID of parent record (for derived/computed data) */
+    parentRecordId?: string | number;
+    /** Parent table name */
+    parentTableName?: string;
+    /** When the record was created */
+    createdAt: Date;
+}
+/** Full lineage chain for a record */
+export interface LineageChain {
+    /** The record ID */
+    recordId: string | number;
+    /** The table name */
+    tableName: string;
+    /** Origin/provenance information */
+    provenance: LineageRecord;
+    /** All transformations applied */
+    transformations: TransformationRecord[];
+    /** Full chain including parent lineages */
+    chain: LineageRecord[];
+}
+/** Options for DataLineage.enable() */
+export interface LineageOptions {
+    /** Custom table name for lineage storage. Default: 'DataLineageRecords' */
+    tableName?: string;
+    /** Function to get current user ID */
+    getUserId?: () => string | number | undefined;
+    /** Whether to automatically track all creates/updates. Default: true */
+    autoTrack?: boolean;
+    /** Fields to track specifically (used with decorator) */
+    trackedFields?: string[];
+    /** Whether to integrate with AuditLogger. Default: true */
+    integrateWithAudit?: boolean;
+}
+interface LineageConfig {
+    model: any;
+    prorm: Prorm;
+    options: Required<LineageOptions>;
+    lineageModel: ModelStatic<any>;
+    transformationModel: ModelStatic<any>;
+}
+export interface LineageTrackOptions {
+    /** Fields to specifically track for lineage */
+    fields?: string[];
+    /** Custom source type for decorated model */
+    source?: DataSource;
+    /** Source details template */
+    sourceDetails?: string;
+}
+/**
+ * Decorator to mark fields for lineage tracking.
+ *
+ *   @LineageTrack({ fields: ['amount', 'total', 'tax'] })
+ *   class Order extends Model { ... }
+ */
+export declare function LineageTrack(options?: LineageTrackOptions): (target: Function) => void;
+/**
+ * Get the lineage fields for a model.
+ */
+export declare function getLineageFields(Model: any): string[];
+/**
+ * Get the lineage options for a model.
+ */
+export declare function getLineageOptions(Model: any): LineageTrackOptions | undefined;
+export declare class DataLineage {
+    /**
+     * Enable lineage tracking on a model.
+     * Creates necessary tables and registers hooks.
+     *
+     * @param model     - The model class to track
+     * @param prorm - The Prorm instance
+     * @param options   - Optional configuration
+     */
+    static enable(model: any, prorm: Prorm, options?: LineageOptions): void;
+    /**
+     * Apply hooks to a model for automatic lineage tracking.
+     * Called automatically by enable() when autoTrack is true.
+     *
+     * @param model  - The model class
+     * @param config - The lineage configuration
+     */
+    static applyHooks(model: any, config?: LineageConfig): void;
+    /**
+     * Track a data source for a record.
+     * Call this when data is imported or computed.
+     *
+     * @param model   - The model class
+     * @param source  - The data source type
+     * @param details - Additional details about the source
+     */
+    static trackSource(model: any, source: DataSource, details?: {
+        sourceDetails?: string;
+        metadata?: Record<string, any>;
+        parentRecordId?: string | number;
+        parentTableName?: string;
+    }): Promise<void>;
+    /**
+     * Track a transformation for a record.
+     *
+     * @param model      - The model class
+     * @param recordId   - The record ID
+     * @param operation  - The transformation operation
+     * @param details    - Additional transformation details
+     */
+    static trackTransformation(model: any, recordId: string | number, operation: string, details?: {
+        description?: string;
+        performedBy?: string | number;
+        inputValues?: Record<string, any>;
+        outputValues?: Record<string, any>;
+        metadata?: Record<string, any>;
+    }): Promise<void>;
+    /**
+     * Get the full lineage chain for a record.
+     * Includes provenance and all transformations.
+     *
+     * @param recordId   - The record ID
+     * @param tableName  - The table name
+     */
+    static getLineage(recordId: string | number, tableName: string): Promise<LineageChain | null>;
+    /**
+     * Get just the provenance/origin for a record.
+     *
+     * @param recordId   - The record ID
+     * @param tableName  - The table name
+     */
+    static getProvenance(recordId: string | number, tableName: string): Promise<LineageRecord | null>;
+    /**
+     * Get transformation history for a record.
+     *
+     * @param recordId   - The record ID
+     * @param tableName  - The table name
+     */
+    static getTransformations(recordId: string | number, tableName: string): Promise<TransformationRecord[]>;
+    /**
+     * Disable lineage tracking for a model.
+     *
+     * @param model - The model class
+     */
+    static disable(model: any): void;
+    /**
+     * Get the lineage model for a model.
+     *
+     * @param model - The model class
+     */
+    static getLineageModel(model: any): ModelStatic<any> | undefined;
+    /**
+     * Get the transformation model for a model.
+     *
+     * @param model - The model class
+     */
+    static getTransformationModel(model: any): ModelStatic<any> | undefined;
+    /**
+     * List all models with lineage tracking enabled.
+     */
+    static listTrackedModels(): Array<{
+        modelName: string;
+        options: LineageOptions;
+    }>;
+    /**
+     * Check if a model has lineage tracking enabled.
+     *
+     * @param model - The model class
+     */
+    static isEnabled(model: any): boolean;
+}
+/**
+ * Apply hooks to a model (exported for convenience).
+ *
+ * @param model - The model class
+ */
+export declare function applyHooks(model: any): void;
+/**
+ * Create a derived record with lineage tracking.
+ * Useful for creating aggregated or computed records.
+ *
+ * @param model      - The model class
+ * @param data      - The data to create
+ * @param parentId  - The parent record ID
+ */
+export declare function createDerivedRecord(model: any, data: Record<string, any>, parentId: string | number): Promise<any>;
+/**
+ * Create a computed record with lineage tracking.
+ * Useful for creating calculated fields.
+ *
+ * @param model     - The model class
+ * @param data      - The computed data
+ * @param inputData - The input values used in computation
+ */
+export declare function createComputedRecord(model: any, data: Record<string, any>, inputData?: Record<string, any>): Promise<any>;
+export {};

package/dist/compliance/data-masker.d.ts

@@ -0,0 +1,110 @@
+/**
+ * DataMasker
+ *
+ * Masks sensitive fields in query output. Supports built-in masking patterns
+ * (PAN, SSN, email, phone) and custom patterns. Works with the permission
+ * system to provide role-aware masking.
+ *
+ * Covers ~14 compliance frameworks including:
+ *   PCI DSS (cardholder data), GLBA (financial), SOX, HIPAA,
+ *   NYDFS 23 NYCRR 500, GDPR Art 25/32, NIST SP 800-122, and more.
+ *
+ * Usage:
+ *   // Register a masking rule:
+ *   DataMasker.maskField(User, 'ssn', { pattern: 'ssn' });
+ *   DataMasker.maskField(Payment, 'cardNumber', { pattern: 'card-last4', showLast: 4 });
+ *   DataMasker.maskField(Customer, 'email', { pattern: 'email' });
+ *
+ *   // Or use the decorator:
+ *   @Mask('ssn', { pattern: 'ssn' })
+ *   class User extends Model { ... }
+ *
+ *   // At query time, mask the output:
+ *   const user = await User.findByPk(1);
+ *   const masked = DataMasker.mask(user, 'admin'); // respects role
+ *
+ *   // Or use the automatic hook:
+ *   DataMasker.applyHooks(User);
+ */
+/** Built-in masking pattern identifiers; see {@link MaskPatternEnum} for the enum form. */
+export type MaskPattern = 'ssn' | 'card-last4' | 'card-first6' | 'email' | 'phone' | 'full' | 'none' | 'custom';
+/**
+ * Companion enum for {@link MaskPattern}. Provided for callers who prefer
+ * enum-based ergonomics (autocomplete, refactor-safety) over raw string
+ * literals. The underlying values are identical to the `MaskPattern`
+ * string literals, so either form may be used interchangeably.
+ */
+export declare enum MaskPatternEnum {
+    SSN = "ssn",
+    CardLast4 = "card-last4",
+    CardFirst6 = "card-first6",
+    Email = "email",
+    Phone = "phone",
+    Full = "full",
+    None = "none",
+    Custom = "custom"
+}
+export interface MaskOptions {
+    /** The masking pattern to apply */
+    pattern?: MaskPattern | MaskPatternEnum;
+    /** For custom pattern, a function that transforms the value */
+    customMasker?: (value: string) => string;
+    /** Number of trailing characters to show (for card-last4, etc.) */
+    showLast?: number;
+    /** Number of leading characters to show */
+    showFirst?: number;
+    /** Character to use for masking. Default: '*' */
+    maskChar?: string;
+}
+interface MaskRule {
+    field: string;
+    options: MaskOptions;
+}
+/**
+ * Register a masking rule for a field on a model.
+ */
+export declare function maskField(Model: any, field: string, options?: MaskOptions): void;
+/**
+ * Get all masking rules for a model.
+ */
+export declare function getMaskRules(Model: any): MaskRule[];
+/**
+ * Decorator to mark a field for masking.
+ *
+ *   @Mask('ssn', { pattern: 'ssn' })
+ *   class User extends Model { ... }
+ */
+export declare function Mask(field: string, options?: MaskOptions): (target: Function) => void;
+/**
+ * Apply masking to a single value.
+ */
+export declare function maskValue(value: any, options: MaskOptions): string;
+/**
+ * Apply masking to a model instance, respecting both permission rules
+ * and masking rules.
+ *
+ * @param instance - The model instance or plain object
+ * @param role     - The current user's role (for permission filtering)
+ * @param Model    - The model class (optional, inferred from instance.constructor)
+ */
+export declare function mask(instance: any, role: string, Model?: any): Record<string, any>;
+/**
+ * Apply masking to an array of instances.
+ */
+export declare function maskMany(instances: any[], role: string, Model?: any): Record<string, any>[];
+/**
+ * Wire afterFind hooks onto a model to automatically mask results.
+ *
+ *   DataMasker.applyHooks(User);
+ */
+export declare function applyHooks(Model: any): void;
+/** Static facade bundling the masking API (mirrors the module-level functions). */
+export declare class DataMasker {
+    static maskField: typeof maskField;
+    static getRules: typeof getMaskRules;
+    static mask: typeof mask;
+    static maskMany: typeof maskMany;
+    static maskValue: typeof maskValue;
+    static applyHooks: typeof applyHooks;
+}
+export {};

package/dist/compliance/data-portability.d.ts

@@ -0,0 +1,98 @@
+/**
+ * DataPortabilityExporter
+ *
+ * Exports data in machine-readable formats (JSON, CSV, NDJSON) for
+ * GDPR Art 20 / CCPA / CPRA data subject access requests (DSARs).
+ * Respects field-level permissions — strips restricted fields from export.
+ *
+ * Covers ~25 compliance frameworks including:
+ *   GDPR Art 20, CCPA, CPRA, LGPD, APPI, PDPA (Singapore, Philippines),
+ *   PoPI (South Africa), PIPEDA, and other data portability rights.
+ *
+ * Usage:
+ *   // Export all data for a user (JSON):
+ *   const export = await DataPortabilityExporter.export(User, {
+ *     where: { id: userId },
+ *     format: 'json',
+ *   });
+ *
+ *   // Export in CSV format:
+ *   const csv = await DataPortabilityExporter.export(User, {
+ *     where: { id: userId },
+ *     format: 'csv',
+ *     include: [Order, Address],  // also export associated models
+ *   });
+ *
+ *   // Export as NDJSON (newline-delimited JSON, better for large datasets):
+ *   const ndjson = await DataPortabilityExporter.export(User, {
+ *     where: { id: userId },
+ *     format: 'ndjson',
+ *   });
+ *
+ *   // Stream export (for very large datasets):
+ *   await DataPortabilityExporter.exportStream(User, {
+ *     where: { userId },
+ *     format: 'ndjson',
+ *     onChunk: (chunk) => stream.write(chunk),
+ *   });
+ */
+export type ExportFormat = 'json' | 'csv' | 'ndjson';
+export interface ExportOptions {
+    /** Where clause to select records */
+    where?: Record<string, any>;
+    /** Include associated models */
+    include?: any[];
+    /** Output format. Default: 'json' */
+    format?: ExportFormat;
+    /** Roles whose fields should be excluded from export */
+    excludeForRole?: string;
+    /** Maximum records to export. Default: unlimited */
+    limit?: number;
+    /** Order clause */
+    order?: any[];
+}
+export interface StreamExportOptions extends ExportOptions {
+    /** Callback for each chunk of data */
+    onChunk: (chunk: string) => void | Promise<void>;
+    /** Batch size for streaming. Default: 100 */
+    batchSize?: number;
+}
+interface ExportResult {
+    format: ExportFormat;
+    content: string;
+    recordCount: number;
+    exportedAt: Date;
+    includedModels: string[];
+}
+/**
+ * Main export function.
+ */
+export declare function exportData(Model: any, options: ExportOptions): Promise<ExportResult>;
+/**
+ * Stream export for large datasets.
+ * Writes directly to a callback to avoid loading everything in memory.
+ */
+export declare function exportStream(Model: any, options: StreamExportOptions): Promise<{
+    recordCount: number;
+    exportedAt: Date;
+}>;
+/**
+ * Generate a DSAR response object ready for API return.
+ */
+export declare function createDSARResponse(subjectId: string, models: Array<{
+    model: any;
+    where?: Record<string, any>;
+}>, options?: {
+    format?: ExportFormat;
+    include?: any[];
+}): Promise<{
+    subjectId: string;
+    requestedAt: Date;
+    exports: ExportResult[];
+}>;
+export declare class DataPortabilityExporter {
+    static export: typeof exportData;
+    static exportStream: typeof exportStream;
+    static createDSARResponse: typeof createDSARResponse;
+}
+export {};

package/dist/compliance/data-retention.d.ts

@@ -0,0 +1,108 @@
+/**
+ * DataRetentionPolicy
+ *
+ * Attach a mandatory data retention period to any model.
+ * Records older than the policy window are purged (deleted or anonymized)
+ * when DataRetentionPolicy.purge() is called.
+ *
+ * Covers ~80 compliance frameworks including:
+ *   GDPR (storage limitation), SOX (7yr), MiFID II (5yr), SEC 17a-4,
+ *   FINRA, HIPAA, PIPEDA, LGPD, APPI, PDPA variants, and more.
+ *
+ * Usage:
+ *   // Set a 7-year retention on financial records:
+ *   DataRetentionPolicy.set(FinancialRecord, {
+ *     maxAge: { years: 7 },
+ *     field: 'createdAt',
+ *     onExpiry: 'delete',
+ *   });
+ *
+ *   // Purge expired records (call from a scheduled job):
+ *   const { deleted } = await DataRetentionPolicy.purge(FinancialRecord, prorm);
+ *
+ *   // Or purge all registered models:
+ *   const report = await DataRetentionPolicy.purgeAll(prorm);
+ */
+export interface RetentionDuration {
+    years?: number;
+    months?: number;
+    days?: number;
+    hours?: number;
+    /** Direct millisecond override — takes precedence over the above. */
+    ms?: number;
+}
+export type RetentionExpiryMode = 'delete' | 'anonymize';
+export interface RetentionPolicyOptions {
+    /**
+     * Maximum age of records to keep.
+     * Records older than this will be purged.
+     */
+    maxAge: RetentionDuration;
+    /**
+     * The date field used to determine record age.
+     * Default: 'createdAt'
+     */
+    field?: string;
+    /**
+     * What to do when a record expires.
+     * 'delete'    — hard delete the row (default)
+     * 'anonymize' — set all string/non-id fields to null
+     */
+    onExpiry?: RetentionExpiryMode;
+    /**
+     * Fields to preserve during anonymization (only relevant when onExpiry='anonymize').
+     * Primary key and the date field are always preserved.
+     */
+    preserveFields?: string[];
+}
+export declare class DataRetentionPolicy {
+    /**
+     * Register a retention policy on a model.
+     * This does not start any background process — call purge() on a schedule.
+     *
+     * @param model   - The model class
+     * @param options - Retention configuration
+     */
+    static set(model: any, options: RetentionPolicyOptions): void;
+    /**
+     * Remove the retention policy from a model.
+     */
+    static unset(model: any): void;
+    /**
+     * Get the registered policy for a model, or undefined.
+     */
+    static get(model: any): RetentionPolicyOptions | undefined;
+    /**
+     * Purge expired records for a specific model.
+     *
+     * @param model     - The model class
+     * @param prorm - The Prorm instance (for Op support)
+     * @returns Number of records deleted or anonymized
+     */
+    static purge(model: any, prorm?: any): Promise<{
+        affected: number;
+        mode: string;
+    }>;
+    /**
+     * Purge all models that have a registered retention policy.
+     *
+     * @param prorm - The Prorm instance
+     * @returns A map of model name → purge result
+     */
+    static purgeAll(prorm?: any): Promise<Map<string, {
+        affected: number;
+        mode: string;
+    }>>;
+    /**
+     * List all models with registered retention policies.
+     */
+    static listPolicies(): Array<{
+        modelName: string;
+        options: RetentionPolicyOptions;
+    }>;
+    /**
+     * Calculate the cutoff date for a given retention duration.
+     * Useful for displaying "records older than X will be deleted on Y".
+     */
+    static cutoffDate(maxAge: RetentionDuration): Date;
+}