ts-prorm-orm 1.1.0 → 1.2.0

package/dist/utils/string.d.ts

@@ -0,0 +1,88 @@
+/**
+ * String utility functions
+ */
+export interface StringUtils {
+    upperCase: (str: string) => string;
+    lowerCase: (str: string) => string;
+    capitalize: (str: string) => string;
+    capitalizeWords: (str: string) => string;
+    trim: (str: string) => string;
+    ltrim: (str: string) => string;
+    rtrim: (str: string) => string;
+    trimStart: (str: string) => string;
+    trimEnd: (str: string) => string;
+    pad: (str: string, length: number, char?: string, direction?: 'left' | 'right' | 'both') => string;
+    truncate: (str: string, maxLength: number, suffix?: string) => string;
+    padStart: (str: string, length: number, char?: string) => string;
+    padEnd: (str: string, length: number, char?: string) => string;
+}
+export declare const regex: {
+    email: RegExp;
+    url: RegExp;
+    uuid: RegExp;
+    phone: RegExp;
+    numeric: RegExp;
+    alpha: RegExp;
+    alphanumeric: RegExp;
+    hexColor: RegExp;
+    isoDate: RegExp;
+    json: RegExp;
+    strongPassword: RegExp;
+};
+/**
+ * Convert a string to uppercase
+ */
+export declare function upperCase(str: string): string;
+/**
+ * Convert a string to lowercase
+ */
+export declare function lowerCase(str: string): string;
+/**
+ * Capitalize first letter of a string
+ */
+export declare function capitalize(str: string): string;
+/**
+ * Capitalize first letter of each word
+ */
+export declare function capitalizeWords(str: string): string;
+/**
+ * Trim whitespace from both ends
+ */
+export declare function trim(str: string): string;
+/**
+ * Trim whitespace from start
+ */
+export declare function trimStart(str: string): string;
+/**
+ * Trim whitespace from end
+ */
+export declare function trimEnd(str: string): string;
+/**
+ * Trim whitespace from start (alias for trimStart)
+ */
+export declare function ltrim(str: string): string;
+/**
+ * Trim whitespace from end (alias for trimEnd)
+ */
+export declare function rtrim(str: string): string;
+/**
+ * Pad string to specified length
+ */
+export declare function pad(str: string, length: number, char?: string, direction?: 'left' | 'right' | 'both'): string;
+/**
+ * Pad string at start
+ */
+export declare function padStart(str: string, length: number, char?: string): string;
+/**
+ * Pad string at end
+ */
+export declare function padEnd(str: string, length: number, char?: string): string;
+/**
+ * Truncate string to specified length
+ */
+export declare function truncate(str: string, maxLength: number, suffix?: string): string;
+/**
+ * String utilities object for convenient access
+ */
+export declare const stringUtils: StringUtils;
+export default stringUtils;

package/dist/validators/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validators Module
+ * Exports all validation functionality
+ */
+export { Validator, ValidationError, validate, validateField, validateAsync, validateFieldAsync, createValidationError, getValidatorsForDataType, registerValidatorModel, unregisterValidatorModel, getValidatorModel, } from './validator';
+export type { ValidationRule, ValidatorConfig, ValidationResult, AsyncValidationContext, UniqueCheckModel, } from './validator';
+export type { ValidationErrorItem } from '../types';

package/dist/validators/validator.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Validator System for the TypeScript ORM
+ * Provides comprehensive validation methods and utilities
+ */
+import type { ValidationErrorItem } from '../types';
+/**
+ * Custom validation error class that extends Error
+ * Contains an array of validation error items
+ */
+export declare class ValidationError extends Error {
+    errors: ValidationErrorItem[];
+    constructor(message?: string, errors?: ValidationErrorItem[]);
+    /**
+     * Add an error to the validation errors array
+     */
+    addError(error: ValidationErrorItem): void;
+    /**
+     * Check if there are any validation errors
+     */
+    hasErrors(): boolean;
+    /**
+     * Get errors for a specific field
+     */
+    getErrorsForField(path: string): ValidationErrorItem[];
+}
+/**
+ * Validation rule definition
+ */
+export type ValidationRule = boolean | string | number | RegExp | ValidationRule[];
+/**
+ * Validator configuration object
+ * Maps field names to their validation rules
+ */
+export interface ValidatorConfig {
+    [field: string]: {
+        [rule: string]: ValidationRule;
+    };
+}
+/**
+ * Validation result from running validators
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationErrorItem[];
+}
+/**
+ * Minimal shape required from a Model class to support a real database
+ * uniqueness check. `src/models/model.ts` model classes (and the static
+ * side of `ModelInstance`) satisfy this shape via their `findOne` method.
+ */
+export interface UniqueCheckModel {
+    findOne(options: {
+        where: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+/**
+ * Register a live model class so `isUnique`/`isUniqueAsync` validators can
+ * resolve a `model: 'SomeModelName'` string reference to a real class with
+ * a working `findOne`.
+ */
+export declare function registerValidatorModel(name: string, model: UniqueCheckModel): void;
+/**
+ * Remove a previously registered model reference.
+ */
+export declare function unregisterValidatorModel(name: string): void;
+/**
+ * Look up a registered model reference by name.
+ */
+export declare function getValidatorModel(name: string): UniqueCheckModel | undefined;
+/**
+ * Validator class with built-in validation methods
+ * Provides comprehensive validation for various data types
+ */
+export declare class Validator {
+    /**
+     * Check if value is a valid email address
+     */
+    static isEmail(value: unknown): boolean;
+    /**
+     * Check if value is a valid URL
+     */
+    static isUrl(value: unknown): boolean;
+    /**
+     * Check if value is a valid IP address (IPv4 or IPv6)
+     */
+    static isIP(value: unknown): boolean;
+    /**
+     * Check if value contains only alphabetic characters
+     */
+    static isAlpha(value: unknown): boolean;
+    /**
+     * Check if value contains only alphanumeric characters
+     */
+    static isAlphanumeric(value: unknown): boolean;
+    /**
+     * Check if value contains only numeric characters
+     */
+    static isNumeric(value: unknown): boolean;
+    /**
+     * Check if value is an integer
+     */
+    static isInt(value: unknown): boolean;
+    /**
+     * Check if value is a floating-point number
+     */
+    static isFloat(value: unknown): boolean;
+    /**
+     * Check if value is a decimal number
+     */
+    static isDecimal(value: unknown): boolean;
+    /**
+     * Check if value is a boolean
+     */
+    static isBoolean(value: unknown): boolean;
+    /**
+     * Check if value is a valid date
+     */
+    static isDate(value: unknown): boolean;
+    /**
+     * Check if value is a valid time string (HH:MM or HH:MM:SS)
+     */
+    static isTime(value: unknown): boolean;
+    /**
+     * Check if value is a valid date string (ISO 8601)
+     */
+    static isDateString(value: unknown): boolean;
+    /**
+     * Check if value is a valid UUID (version 1, 4, 5)
+     */
+    static isUUID(value: unknown): boolean;
+    /**
+     * Check if value is valid JSON
+     */
+    static isJSON(value: unknown): boolean;
+    /**
+     * Check if value is empty (null, undefined, or empty string)
+     */
+    static isEmpty(value: unknown): boolean;
+    /**
+     * Check if value is not empty
+     */
+    static notEmpty(value: unknown): boolean;
+    /**
+     * Check if string length is within bounds
+     * @param value - The value to check
+     * @param len - Single number for exact length, or [min, max] tuple
+     */
+    static len(value: unknown, len: number | [number, number]): boolean;
+    /**
+     * Check if numeric value is >= minimum
+     */
+    static min(value: unknown, minVal: number): boolean;
+    /**
+     * Check if numeric value is <= maximum
+     */
+    static max(value: unknown, maxVal: number): boolean;
+    /**
+     * Check if numeric value is within range
+     */
+    static range(value: unknown, range: [number, number]): boolean;
+    /**
+     * Check if value is in the allowed list
+     */
+    static isIn(value: unknown, values: unknown[]): boolean;
+    /**
+     * Check if value is not in the disallowed list
+     */
+    static notIn(value: unknown, values: unknown[]): boolean;
+    /**
+     * Synchronous uniqueness check.
+     *
+     * A real uniqueness check requires an async database query, which cannot
+     * be performed from a synchronous function. This method exists only for
+     * backwards compatibility with call sites that still use the
+     * synchronous `validate()`/`validateField()` entry points; it always
+     * returns `true` (never fails validation) and logs a warning so silent
+     * false-passes are visible.
+     *
+     * Prefer `Validator.isUniqueAsync()` (via `validateAsync()`/
+     * `validateFieldAsync()`) wherever a real database uniqueness check is
+     * required.
+     */
+    static isUnique(value: unknown, options?: {
+        model?: string | UniqueCheckModel;
+        field?: string;
+        where?: Record<string, unknown>;
+    }): boolean;
+    /**
+     * Check if value is unique by performing a real database lookup via
+     * `Model.findOne()`.
+     *
+     * @param value - The value to check for uniqueness
+     * @param options.model - Either a model name registered via
+     *   `registerValidatorModel()`, or a live model reference (any object
+     *   exposing an async `findOne({ where })` method, e.g. a Model class).
+     * @param options.field - The column/attribute name to check. Defaults to
+     *   the field the rule was declared on when used via `validateAsync`.
+     * @param options.where - Extra where conditions to scope the lookup
+     *   (e.g. multi-column uniqueness, soft-delete scoping).
+     * @param options.exclude - Primary-key (or other) conditions identifying
+     *   the current instance, so an update does not fail uniqueness against
+     *   itself. Each entry is turned into a `{ [Op.ne]: value }` condition.
+     */
+    static isUniqueAsync(value: unknown, options?: {
+        model?: string | UniqueCheckModel;
+        field?: string;
+        where?: Record<string, unknown>;
+        exclude?: Record<string, unknown>;
+    }): Promise<boolean>;
+    /**
+     * Check if value equals the expected value
+     */
+    static equals(value: unknown, expected: unknown): boolean;
+    /**
+     * Check if value does not equal the expected value
+     */
+    static notEquals(value: unknown, expected: unknown): boolean;
+    /**
+     * Check if value matches a regular expression
+     */
+    static matches(value: unknown, pattern: RegExp | string): boolean;
+    /**
+     * Check if value does not match a regular expression
+     */
+    static notMatches(value: unknown, pattern: RegExp | string): boolean;
+    /**
+     * Check if value is a valid credit card number (Luhn algorithm)
+     */
+    static isCreditCard(value: unknown): boolean;
+    /**
+     * Check if value is a valid postal code
+     */
+    static isPostalCode(value: unknown, locale?: string): boolean;
+    /**
+     * Check if value is a valid phone number
+     */
+    static isMobilePhone(value: unknown, locale?: string): boolean;
+    /**
+     * Check if value is a valid hexadecimal color
+     */
+    static isHexColor(value: unknown): boolean;
+    /**
+     * Check if string contains only lowercase characters
+     */
+    static isLowercase(value: unknown): boolean;
+    /**
+     * Check if string contains only uppercase characters
+     */
+    static isUppercase(value: unknown): boolean;
+}
+/**
+ * Run all validators on data and return validation result
+ * @param data - The data object to validate
+ * @param validators - The validator configuration
+ * @returns Validation result with valid flag and errors array
+ */
+export declare function validate(data: Record<string, unknown>, validators: ValidatorConfig): ValidationResult;
+/**
+ * Validate a single field with given rules
+ */
+export declare function validateField(value: unknown, rules: Record<string, ValidationRule>): ValidationResult;
+/**
+ * Async validation context passed to `validateAsync`/`validateFieldAsync`
+ * so an `isUnique` rule can exclude the current instance (e.g. by primary
+ * key) when validating an update, instead of failing uniqueness against
+ * itself.
+ */
+export interface AsyncValidationContext {
+    /** Conditions identifying the current instance, e.g. `{ id: 5 }`. */
+    exclude?: Record<string, unknown>;
+}
+/**
+ * Async counterpart to `validate()` that performs a real database
+ * uniqueness check for `isUnique` rules (via `Validator.isUniqueAsync`)
+ * instead of always passing.
+ *
+ * @param data - The data object to validate
+ * @param validators - The validator configuration
+ * @param context - Optional async context, e.g. `{ exclude: { id: 5 } }`
+ *   to exclude the current record from the uniqueness lookup on update.
+ */
+export declare function validateAsync(data: Record<string, unknown>, validators: ValidatorConfig, context?: AsyncValidationContext): Promise<ValidationResult>;
+/**
+ * Async counterpart to `validateField()` - see `validateAsync`.
+ */
+export declare function validateFieldAsync(value: unknown, rules: Record<string, ValidationRule>, context?: AsyncValidationContext & {
+    field?: string;
+}): Promise<ValidationResult>;
+/**
+ * Create a ValidationError from validation result
+ */
+export declare function createValidationError(result: ValidationResult): ValidationError;
+/**
+ * Get validation rules based on DataType
+ * Useful for automatic validation based on column type
+ */
+export declare function getValidatorsForDataType(dataType: string): Record<string, ValidationRule>;
+declare const _default: {
+    Validator: typeof Validator;
+    ValidationError: typeof ValidationError;
+    validate: typeof validate;
+    validateField: typeof validateField;
+    createValidationError: typeof createValidationError;
+    getValidatorsForDataType: typeof getValidatorsForDataType;
+};
+export default _default;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "ts-prorm-orm",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "main": "dist/index.js",
-  "types": "dist/types/index.d.ts",
+  "types": "dist/index.d.ts",
   "author": "Malcolm Stone",
   "license": "MIT",
   "description": "A TypeScript ORM for MySQL, PostgreSQL, SQLite, MSSQL, and more",
@@ -51,9 +51,10 @@
     "test:db:down": "docker compose -f docker-compose.test.yml down -v",
     "test:db:up:no-oracle": "docker compose -f docker-compose.test.yml up -d --wait postgres mysql mariadb mssql cockroachdb clickhouse",
     "test:integration": "INTEGRATION=1 jest -c jest.integration.config.js",
-    "prepublishOnly": "npm run build && npm run test",
+    "prepublishOnly": "npm run build && npm run check:package && npm run test",
     "prepare": "husky",
-    "docs:reference": "typedoc"
+    "docs:reference": "typedoc",
+    "check:package": "node scripts/check-package.mjs"
   },
   "bin": {
     "prorm": "dist/cli.js",
@@ -140,6 +141,15 @@
     "testMatch": [
       "**/tests/**/*.test.ts"
     ],
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "/\\.claude/",
+      "/dist/"
+    ],
+    "modulePathIgnorePatterns": [
+      "<rootDir>/\\.claude/",
+      "<rootDir>/dist/"
+    ],
     "moduleFileExtensions": [
       "ts",
       "tsx",
@@ -168,7 +178,8 @@
       "default",
       "jest-junit"
     ],
-    "workerIdleMemoryLimit": "256MB"
+    "workerIdleMemoryLimit": "256MB",
+    "coverageProvider": "v8"
   },
   "jest-junit": {
     "outputDirectory": ".",
@@ -186,5 +197,9 @@
   },
   "optionalDependencies": {
     "pg-copy-streams": "^7.0.0"
+  },
+  "allowScripts": {
+    "better-sqlite3@12.8.0": true,
+    "duckdb@1.4.4": true
   }
 }