@ductape/sdk 0.0.4-v6 → 0.0.4-v61

package/dist/database/types/presave.interface.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Pre-save operations type definitions
+ *
+ * Pre-save operations are transformations applied to data before it's written
+ * to the database. They support encryption, hashing, masking, validation,
+ * sanitization, and custom transformations.
+ */
+/**
+ * Types of pre-save operations available
+ */
+export declare enum PreSaveOperationType {
+    /** Encrypt field value using AES-256 */
+    ENCRYPT = "encrypt",
+    /** Hash field value (one-way, e.g., for passwords) */
+    HASH = "hash",
+    /** Mask sensitive data (e.g., credit card: **** **** **** 1234) */
+    MASK = "mask",
+    /** Trim whitespace from string */
+    TRIM = "trim",
+    /** Convert to lowercase */
+    LOWERCASE = "lowercase",
+    /** Convert to uppercase */
+    UPPERCASE = "uppercase",
+    /** Sanitize HTML/script tags */
+    SANITIZE = "sanitize",
+    /** Validate and throw if invalid */
+    VALIDATE = "validate",
+    /** Transform with custom function */
+    TRANSFORM = "transform",
+    /** Generate UUID */
+    UUID = "uuid",
+    /** Generate slug from another field */
+    SLUG = "slug",
+    /** Set to current timestamp */
+    TIMESTAMP = "timestamp",
+    /** Round number to specified decimals */
+    ROUND = "round",
+    /** Clamp number to min/max range */
+    CLAMP = "clamp",
+    /** Truncate string to max length */
+    TRUNCATE = "truncate",
+    /** Default value if null/undefined */
+    DEFAULT = "default",
+    /** Normalize phone number */
+    NORMALIZE_PHONE = "normalizePhone",
+    /** Normalize email (lowercase, trim) */
+    NORMALIZE_EMAIL = "normalizeEmail",
+    /** Parse JSON string to object */
+    PARSE_JSON = "parseJson",
+    /** Stringify object to JSON */
+    STRINGIFY_JSON = "stringifyJson",
+    /** Compute derived field from other fields */
+    COMPUTE = "compute"
+}
+/**
+ * Base options for all pre-save operations
+ */
+export interface IPreSaveBaseOptions {
+    /** Field name to apply operation to */
+    field: string;
+    /** Operation type */
+    type: PreSaveOperationType;
+    /** Skip operation if field is null/undefined */
+    skipIfNull?: boolean;
+    /** Skip operation if field is empty string */
+    skipIfEmpty?: boolean;
+    /** Condition function - only apply if returns true */
+    condition?: (data: Record<string, any>) => boolean;
+}
+/**
+ * Encryption options
+ */
+export interface IPreSaveEncryptOptions extends IPreSaveBaseOptions {
+    type: PreSaveOperationType.ENCRYPT;
+    /** Encryption algorithm (default: aes-256-gcm) */
+    algorithm?: 'aes-256-gcm' | 'aes-256-cbc' | 'aes-128-gcm';
+    /** Encryption key (or use default from config) */
+    key?: string;
+    /** Store IV alongside encrypted data (required for decryption) */
+    storeIV?: boolean;
+    /** Field to store IV in (default: `${field}_iv`) */
+    ivField?: string;
+}
+/**
+ * Hash options (for passwords, etc.)
+ */
+export interface IPreSaveHashOptions extends IPreSaveBaseOptions {
+    type: PreSaveOperationType.HASH;
+    /** Hash algorithm */
+    algorithm?: 'bcrypt' | 'argon2' | 'sha256' | 'sha512' | 'md5';
+    /** Salt rounds for bcrypt (default: 10) */
+    saltRounds?: number;
+    /** Custom salt (if not using bcrypt) */
+    salt?: string;
+}
+/**
+ * Mask options
+ */
+export interface IPreSaveMaskOptions extends IPreSaveBaseOptions {
+    type: PreSaveOperationType.MASK;
+    /** Mask pattern: 'credit-card', 'ssn', 'phone', 'email', or custom */
+    pattern?: 'credit-card' | 'ssn' | 'phone' | 'email' | 'custom';
+    /** For custom pattern: character to mask with (default: '*') */
+    maskChar?: string;
+    /** For custom pattern: number of characters to show at start */
+    showFirst?: number;
+    /** For custom pattern: number of characters to show at end */
+    showLast?: number;
+    /** Store original value in separate field */
+    storeOriginalIn?: string;
+}
+/**
+ * Validation options
+ */
+export interface IPreSaveValidateOptions extends IPreSaveBaseOptions {
+    type: PreSaveOperationType.VALIDATE;
+    /** Validation rules */
+    rules: IValidationRule[];
+    /** Custom error message */
+    errorMessage?: string;
+    /** Throw on validation failure (default: true) */
+    throwOnFail?: boolean;
+    /** Field to store validation result if not throwing */
+    resultField?: string;
+}
+/**
+ * Validation rule
+ */
+export interface IValidationRule {
+    /** Rule type */
+    type: 'required' | 'email' | 'url' | 'minLength' | 'maxLength' | 'min' | 'max' | 'pattern' | 'enum' | 'custom' | 'type' | 'integer' | 'positive' | 'negative';
+    /** Value for the rule (min, max, pattern, enum values, etc.) */
+    value?: any;
+    /** Custom validation function */
+    validator?: (value: any, data: Record<string, any>) => boolean;
+    /** Error message for this rule */
+    message?: string;
+}
+/**
+ * Transform options (custom function)
+ */
+export interface IPreSaveTransformOptions extends IPreSaveBaseOptions {
+    type: PreSaveOperationType.TRANSFORM;
+    /** Transformation function */
+    transformer: (value: any, data: Record<string, any>) => any;
+}
+/**
+ * Slug options
+ */
+export interface IPreSaveSlugOptions extends IPreSaveBaseOptions {
+    type: PreSaveOperationType.SLUG;
+    /** Source field to generate slug from */
+    sourceField: string;
+    /** Separator character (default: '-') */
+    separator?: string;
+    /** Convert to lowercase (default: true) */
+    lowercase?: boolean;
+    /** Remove special characters (default: true) */
+    removeSpecialChars?: boolean;
+    /** Max length of slug */
+    maxLength?: number;
+}
+/**
+ * Truncate options
+ */
+export interface IPreSaveTruncateOptions extends IPreSaveBaseOptions {
+    type: PreSaveOperationType.TRUNCATE;
+    /** Maximum length */
+    maxLength: number;
+    /** Suffix to add if truncated (default: '...') */
+    suffix?: string;
+    /** Truncate at word boundary */
+    wordBoundary?: boolean;
+}
+/**
+ * Round options
+ */
+export interface IPreSaveRoundOptions extends IPreSaveBaseOptions {
+    type: PreSaveOperationType.ROUND;
+    /** Number of decimal places (default: 2) */
+    decimals?: number;
+    /** Rounding mode */
+    mode?: 'round' | 'floor' | 'ceil';
+}
+/**
+ * Clamp options
+ */
+export interface IPreSaveClampOptions extends IPreSaveBaseOptions {
+    type: PreSaveOperationType.CLAMP;
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+}
+/**
+ * Default value options
+ */
+export interface IPreSaveDefaultOptions extends IPreSaveBaseOptions {
+    type: PreSaveOperationType.DEFAULT;
+    /** Default value to use */
+    value: any;
+    /** Use function to generate default */
+    generator?: (data: Record<string, any>) => any;
+}
+/**
+ * Compute options (derived field)
+ */
+export interface IPreSaveComputeOptions extends IPreSaveBaseOptions {
+    type: PreSaveOperationType.COMPUTE;
+    /** Computation function */
+    compute: (data: Record<string, any>) => any;
+    /** Source fields this computation depends on */
+    dependsOn?: string[];
+}
+/**
+ * Simple operation options (no additional config needed)
+ */
+export interface IPreSaveSimpleOptions extends IPreSaveBaseOptions {
+    type: PreSaveOperationType.TRIM | PreSaveOperationType.LOWERCASE | PreSaveOperationType.UPPERCASE | PreSaveOperationType.SANITIZE | PreSaveOperationType.UUID | PreSaveOperationType.TIMESTAMP | PreSaveOperationType.NORMALIZE_PHONE | PreSaveOperationType.NORMALIZE_EMAIL | PreSaveOperationType.PARSE_JSON | PreSaveOperationType.STRINGIFY_JSON;
+}
+/**
+ * Union type of all pre-save operation options
+ */
+export type IPreSaveOperation = IPreSaveEncryptOptions | IPreSaveHashOptions | IPreSaveMaskOptions | IPreSaveValidateOptions | IPreSaveTransformOptions | IPreSaveSlugOptions | IPreSaveTruncateOptions | IPreSaveRoundOptions | IPreSaveClampOptions | IPreSaveDefaultOptions | IPreSaveComputeOptions | IPreSaveSimpleOptions;
+/**
+ * Pre-save processor configuration
+ */
+export interface IPreSaveConfig {
+    /** Default encryption key (can be overridden per operation) */
+    encryptionKey?: string;
+    /** Default hash algorithm */
+    defaultHashAlgorithm?: 'bcrypt' | 'argon2' | 'sha256' | 'sha512';
+    /** Default bcrypt salt rounds */
+    defaultSaltRounds?: number;
+    /** Whether to throw on validation errors (default: true) */
+    throwOnValidationError?: boolean;
+    /** Custom sanitizer function */
+    sanitizer?: (value: string) => string;
+}
+/**
+ * Pre-save processing result
+ */
+export interface IPreSaveResult {
+    /** Processed data */
+    data: Record<string, any> | Record<string, any>[];
+    /** Operations that were applied */
+    appliedOperations: IAppliedOperation[];
+    /** Validation errors (if any and not throwing) */
+    validationErrors?: IValidationError[];
+    /** Whether processing was successful */
+    success: boolean;
+}
+/**
+ * Applied operation record
+ */
+export interface IAppliedOperation {
+    /** Field name */
+    field: string;
+    /** Operation type */
+    operation: PreSaveOperationType;
+    /** Whether operation was applied */
+    applied: boolean;
+    /** Reason if skipped */
+    skippedReason?: string;
+}
+/**
+ * Validation error
+ */
+export interface IValidationError {
+    /** Field name */
+    field: string;
+    /** Error message */
+    message: string;
+    /** Failed rule type */
+    rule: string;
+    /** Actual value */
+    value?: any;
+}
+/**
+ * Pre-save operations defined at schema level
+ * Can be stored in _ductape_schema for automatic application
+ */
+export interface ISchemaPreSaveConfig {
+    /** Collection/table name */
+    collection: string;
+    /** Operations to apply */
+    operations: IPreSaveOperation[];
+    /** Whether these operations are enabled */
+    enabled: boolean;
+    /** Order of operations (lower numbers run first) */
+    order?: number;
+}

package/dist/database/types/presave.interface.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Pre-save operations type definitions
+ *
+ * Pre-save operations are transformations applied to data before it's written
+ * to the database. They support encryption, hashing, masking, validation,
+ * sanitization, and custom transformations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreSaveOperationType = void 0;
+// ==================== OPERATION TYPES ====================
+/**
+ * Types of pre-save operations available
+ */
+var PreSaveOperationType;
+(function (PreSaveOperationType) {
+    /** Encrypt field value using AES-256 */
+    PreSaveOperationType["ENCRYPT"] = "encrypt";
+    /** Hash field value (one-way, e.g., for passwords) */
+    PreSaveOperationType["HASH"] = "hash";
+    /** Mask sensitive data (e.g., credit card: **** **** **** 1234) */
+    PreSaveOperationType["MASK"] = "mask";
+    /** Trim whitespace from string */
+    PreSaveOperationType["TRIM"] = "trim";
+    /** Convert to lowercase */
+    PreSaveOperationType["LOWERCASE"] = "lowercase";
+    /** Convert to uppercase */
+    PreSaveOperationType["UPPERCASE"] = "uppercase";
+    /** Sanitize HTML/script tags */
+    PreSaveOperationType["SANITIZE"] = "sanitize";
+    /** Validate and throw if invalid */
+    PreSaveOperationType["VALIDATE"] = "validate";
+    /** Transform with custom function */
+    PreSaveOperationType["TRANSFORM"] = "transform";
+    /** Generate UUID */
+    PreSaveOperationType["UUID"] = "uuid";
+    /** Generate slug from another field */
+    PreSaveOperationType["SLUG"] = "slug";
+    /** Set to current timestamp */
+    PreSaveOperationType["TIMESTAMP"] = "timestamp";
+    /** Round number to specified decimals */
+    PreSaveOperationType["ROUND"] = "round";
+    /** Clamp number to min/max range */
+    PreSaveOperationType["CLAMP"] = "clamp";
+    /** Truncate string to max length */
+    PreSaveOperationType["TRUNCATE"] = "truncate";
+    /** Default value if null/undefined */
+    PreSaveOperationType["DEFAULT"] = "default";
+    /** Normalize phone number */
+    PreSaveOperationType["NORMALIZE_PHONE"] = "normalizePhone";
+    /** Normalize email (lowercase, trim) */
+    PreSaveOperationType["NORMALIZE_EMAIL"] = "normalizeEmail";
+    /** Parse JSON string to object */
+    PreSaveOperationType["PARSE_JSON"] = "parseJson";
+    /** Stringify object to JSON */
+    PreSaveOperationType["STRINGIFY_JSON"] = "stringifyJson";
+    /** Compute derived field from other fields */
+    PreSaveOperationType["COMPUTE"] = "compute";
+})(PreSaveOperationType || (exports.PreSaveOperationType = PreSaveOperationType = {}));
+//# sourceMappingURL=presave.interface.js.map

package/dist/database/types/presave.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presave.interface.js","sourceRoot":"","sources":["../../../src/database/types/presave.interface.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,4DAA4D;AAE5D;;GAEG;AACH,IAAY,oBA2CX;AA3CD,WAAY,oBAAoB;IAC9B,wCAAwC;IACxC,2CAAmB,CAAA;IACnB,sDAAsD;IACtD,qCAAa,CAAA;IACb,mEAAmE;IACnE,qCAAa,CAAA;IACb,kCAAkC;IAClC,qCAAa,CAAA;IACb,2BAA2B;IAC3B,+CAAuB,CAAA;IACvB,2BAA2B;IAC3B,+CAAuB,CAAA;IACvB,gCAAgC;IAChC,6CAAqB,CAAA;IACrB,oCAAoC;IACpC,6CAAqB,CAAA;IACrB,qCAAqC;IACrC,+CAAuB,CAAA;IACvB,oBAAoB;IACpB,qCAAa,CAAA;IACb,uCAAuC;IACvC,qCAAa,CAAA;IACb,+BAA+B;IAC/B,+CAAuB,CAAA;IACvB,yCAAyC;IACzC,uCAAe,CAAA;IACf,oCAAoC;IACpC,uCAAe,CAAA;IACf,oCAAoC;IACpC,6CAAqB,CAAA;IACrB,sCAAsC;IACtC,2CAAmB,CAAA;IACnB,6BAA6B;IAC7B,0DAAkC,CAAA;IAClC,wCAAwC;IACxC,0DAAkC,CAAA;IAClC,kCAAkC;IAClC,gDAAwB,CAAA;IACxB,+BAA+B;IAC/B,wDAAgC,CAAA;IAChC,8CAA8C;IAC9C,2CAAmB,CAAA;AACrB,CAAC,EA3CW,oBAAoB,oCAApB,oBAAoB,QA2C/B"}

package/dist/database/types/query.interface.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Query-related type definitions
+ */
+import { SortOrder, RelationshipType } from './enums';
+import { ITransaction } from './transaction.interface';
+/**
+ * Options for querying data
+ */
+export interface IQueryOptions {
+    /** Table or collection name */
+    table: string;
+    /** Columns to select (omit for all columns) */
+    select?: string[];
+    /** Filter conditions */
+    where?: IWhereClause;
+    /** Sort configuration */
+    orderBy?: IOrderBy | IOrderBy[];
+    /** Maximum records to return */
+    limit?: number;
+    /** Records to skip (for pagination) */
+    offset?: number;
+    /** Relationship includes */
+    include?: IInclude | IInclude[];
+    /** Environment (if not using connection context) */
+    env?: string;
+    /** Product tag (if not using connection context) */
+    product?: string;
+    /** Database tag (if not using connection context) */
+    database?: string;
+    /** Transaction to use */
+    transaction?: ITransaction;
+    /** Session token in format: session_tag:jwt_token */
+    session?: string;
+    /** Cache tag for result caching */
+    cache?: string;
+}
+/**
+ * Filter conditions for queries
+ * Supports simple equality, comparison operators, and logical operators
+ */
+export interface IWhereClause {
+    [key: string]: any | IComparisonOperator | ILogicalOperator;
+}
+/**
+ * Comparison operators for filtering
+ * Uses lowercase naming convention to match Mongoose/MongoDB style for less adoption friction
+ */
+export interface IComparisonOperator {
+    /** Equal to */
+    $eq?: any;
+    /** Not equal to */
+    $ne?: any;
+    /** Greater than */
+    $gt?: any;
+    /** Greater than or equal */
+    $gte?: any;
+    /** Less than */
+    $lt?: any;
+    /** Less than or equal */
+    $lte?: any;
+    /** In array of values */
+    $in?: any[];
+    /** Not in array of values */
+    $nin?: any[];
+    /** Pattern match (SQL LIKE) */
+    $like?: string;
+    /** Case-insensitive pattern match (PostgreSQL) */
+    $ilike?: string;
+    /** Between two values [min, max] */
+    $between?: [any, any];
+    /** Is null */
+    $isNull?: boolean;
+    /** Is not null */
+    $isNotNull?: boolean;
+    /** Contains (for arrays/JSONB) */
+    $contains?: any;
+    /** Contained by (for arrays/JSONB) */
+    $containedBy?: any;
+    /** Overlaps (for arrays) */
+    $overlaps?: any[];
+    /** Regex match */
+    $regex?: string | RegExp;
+    /** Exists check */
+    $exists?: boolean;
+}
+/**
+ * Logical operators for combining conditions
+ * Uses lowercase naming convention to match Mongoose/MongoDB style
+ */
+export interface ILogicalOperator {
+    /** All conditions must match */
+    $and?: IWhereClause[];
+    /** Any condition can match */
+    $or?: IWhereClause[];
+    /** Negate condition */
+    $not?: IWhereClause;
+    /** None of the conditions should match */
+    $nor?: IWhereClause[];
+}
+/**
+ * Sort configuration
+ */
+export interface IOrderBy {
+    /** Column name to sort by */
+    column: string;
+    /** Sort order (ASC or DESC) */
+    order: SortOrder | 'ASC' | 'DESC';
+    /** Nulls first or last (PostgreSQL) */
+    nulls?: 'FIRST' | 'LAST';
+}
+/**
+ * Relationship include configuration
+ */
+export interface IInclude {
+    /** Name of the relation (used as key in result) */
+    relation: string;
+    /** Relationship type */
+    type: RelationshipType | 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
+    /** Related table name (optional, defaults to relation name) */
+    table?: string;
+    /** Foreign key column in current table (for many-to-one) or related table (for one-to-many) */
+    foreignKey?: string;
+    /** Primary key column (defaults to 'id') */
+    primaryKey?: string;
+    /** Junction table name (for many-to-many) */
+    through?: string;
+    /** Foreign key in junction table pointing to current table */
+    throughForeignKey?: string;
+    /** Foreign key in junction table pointing to related table */
+    throughRelatedKey?: string;
+    /** Columns to select from related table */
+    select?: string[];
+    /** Filter conditions for related records */
+    where?: IWhereClause;
+    /** Sort configuration for related records */
+    orderBy?: IOrderBy | IOrderBy[];
+    /** Maximum related records to return */
+    limit?: number;
+    /** Nested includes */
+    include?: IInclude | IInclude[];
+}
+/**
+ * Result of a query operation
+ */
+export interface IQueryResult<T> {
+    /** Array of matching records */
+    data: T[];
+    /** Total count (useful for pagination) */
+    count: number;
+    /** Column names (for raw queries) */
+    fields?: string[];
+}
+/**
+ * Options for raw query execution
+ */
+export interface IRawQueryOptions {
+    table: string;
+    /** SQL query string (for SQL databases) or query object (for MongoDB) */
+    query: string | object;
+    /** Query parameters (for parameterized queries) */
+    params?: any[];
+    /** Collection name (for MongoDB) */
+    collection?: string;
+    /** Environment (if not using connection context) */
+    env?: string;
+    /** Product tag */
+    product?: string;
+    /** Database tag */
+    database?: string;
+    /** Transaction to use */
+    transaction?: ITransaction;
+    /** Cache tag for result caching */
+    cache?: string;
+}
+/**
+ * Result of a raw query
+ */
+export interface IRawQueryResult<T> {
+    /** Query results */
+    data: T[];
+    /** Number of affected/returned rows */
+    count: number;
+    /** Column/field names */
+    fields?: string[];
+    /** Rows affected (for INSERT/UPDATE/DELETE) */
+    rowsAffected?: number;
+}
+/**
+ * Internal representation of a built query
+ * Used by adapters to execute database-specific queries
+ */
+export interface IBuiltQuery {
+    /** Original query options */
+    options: IQueryOptions;
+    /** SQL string (for SQL databases) */
+    sql?: string;
+    /** Query parameters */
+    params?: any[];
+    /** MongoDB query (for MongoDB) */
+    mongoQuery?: object;
+    /** MongoDB projection */
+    mongoProjection?: object;
+    /** MongoDB sort */
+    mongoSort?: object;
+}

package/dist/database/types/query.interface.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Query-related type definitions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=query.interface.js.map

package/dist/database/types/query.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.interface.js","sourceRoot":"","sources":["../../../src/database/types/query.interface.ts"],"names":[],"mappings":";AAAA;;GAEG"}