@simtlix/simfinity-js 2.1.0 → 2.2.0

package/README.md

@@ -1101,9 +1101,117 @@ mutation {
 
 ## ✅ Validations
 
-### Field-Level Validations
+### Declarative Validation Helpers
 
-Add validation logic directly to fields:
+Simfinity.js provides built-in validation helpers to simplify common validation patterns, eliminating verbose boilerplate code.
+
+#### Using Validators
+
+```javascript
+const { validators } = require('@simtlix/simfinity-js');
+
+const PersonType = new GraphQLObjectType({
+  name: 'Person',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.stringLength('Name', 2, 100)
+      }
+    },
+    email: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.email()
+      }
+    },
+    website: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.url()
+      }
+    },
+    age: {
+      type: GraphQLInt,
+      extensions: {
+        validations: validators.numberRange('Age', 0, 120)
+      }
+    },
+    price: {
+      type: GraphQLFloat,
+      extensions: {
+        validations: validators.positive('Price')
+      }
+    }
+  })
+});
+```
+
+#### Available Validators
+
+**String Validators:**
+- `validators.stringLength(name, min, max)` - Validates string length with min/max bounds (required for CREATE)
+- `validators.maxLength(name, max)` - Validates maximum string length
+- `validators.pattern(name, regex, message)` - Validates against a regex pattern
+- `validators.email()` - Validates email format
+- `validators.url()` - Validates URL format
+
+**Number Validators:**
+- `validators.numberRange(name, min, max)` - Validates number range
+- `validators.positive(name)` - Ensures number is positive
+
+**Array Validators:**
+- `validators.arrayLength(name, maxItems, itemValidator)` - Validates array length and optionally each item
+
+**Date Validators:**
+- `validators.dateFormat(name, format)` - Validates date format
+- `validators.futureDate(name)` - Ensures date is in the future
+
+#### Validator Features
+
+- **Automatic Operation Handling**: Validators work for both `CREATE` (save) and `UPDATE` operations
+- **Smart Validation**: For CREATE operations, values are required. For UPDATE operations, undefined/null values are allowed (field might not be updated)
+- **Consistent Error Messages**: All validators throw `SimfinityError` with appropriate messages
+
+#### Example: Multiple Validators
+
+```javascript
+const ProductType = new GraphQLObjectType({
+  name: 'Product',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.stringLength('Product Name', 3, 200)
+      }
+    },
+    sku: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.pattern('SKU', /^[A-Z0-9-]+$/, 'SKU must be uppercase alphanumeric with hyphens')
+      }
+    },
+    price: {
+      type: GraphQLFloat,
+      extensions: {
+        validations: validators.positive('Price')
+      }
+    },
+    tags: {
+      type: new GraphQLList(GraphQLString),
+      extensions: {
+        validations: validators.arrayLength('Tags', 10)
+      }
+    }
+  })
+});
+```
+
+### Field-Level Validations (Manual)
+
+For custom validation logic, you can still write manual validators:
 
 ```javascript
 const { SimfinityError } = require('@simtlix/simfinity-js');
@@ -1189,7 +1297,78 @@ const OrderType = new GraphQLObjectType({
 
 ### Custom Validated Scalar Types
 
-Create custom scalar types with built-in validation. The generated type names follow the pattern `{name}_{baseScalarTypeName}`:
+Create custom scalar types with built-in validation. The generated type names follow the pattern `{name}_{baseScalarTypeName}`.
+
+#### Pre-built Scalars
+
+Simfinity.js provides ready-to-use validated scalars for common patterns:
+
+```javascript
+const { scalars } = require('@simtlix/simfinity-js');
+
+const UserType = new GraphQLObjectType({
+  name: 'User',
+  fields: () => ({
+    id: { type: GraphQLID },
+    email: { type: scalars.EmailScalar },      // Type name: Email_String
+    website: { type: scalars.URLScalar },       // Type name: URL_String
+    age: { type: scalars.PositiveIntScalar },  // Type name: PositiveInt_Int
+    price: { type: scalars.PositiveFloatScalar } // Type name: PositiveFloat_Float
+  }),
+});
+```
+
+**Available Pre-built Scalars:**
+- `scalars.EmailScalar` - Validates email format (`Email_String`)
+- `scalars.URLScalar` - Validates URL format (`URL_String`)
+- `scalars.PositiveIntScalar` - Validates positive integers (`PositiveInt_Int`)
+- `scalars.PositiveFloatScalar` - Validates positive floats (`PositiveFloat_Float`)
+
+#### Factory Functions for Custom Scalars
+
+Create custom validated scalars with parameters:
+
+```javascript
+const { scalars } = require('@simtlix/simfinity-js');
+
+// Create a bounded string scalar (name length between 2-100 characters)
+const NameScalar = scalars.createBoundedStringScalar('Name', 2, 100);
+
+// Create a bounded integer scalar (age between 0-120)
+const AgeScalar = scalars.createBoundedIntScalar('Age', 0, 120);
+
+// Create a bounded float scalar (rating between 0-10)
+const RatingScalar = scalars.createBoundedFloatScalar('Rating', 0, 10);
+
+// Create a pattern-based string scalar (phone number format)
+const PhoneScalar = scalars.createPatternStringScalar(
+  'Phone',
+  /^\+?[\d\s\-()]+$/,
+  'Invalid phone number format'
+);
+
+// Use in your types
+const PersonType = new GraphQLObjectType({
+  name: 'Person',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: NameScalar },        // Type name: Name_String
+    age: { type: AgeScalar },          // Type name: Age_Int
+    rating: { type: RatingScalar },    // Type name: Rating_Float
+    phone: { type: PhoneScalar }       // Type name: Phone_String
+  }),
+});
+```
+
+**Available Factory Functions:**
+- `scalars.createBoundedStringScalar(name, min, max)` - String with length bounds
+- `scalars.createBoundedIntScalar(name, min, max)` - Integer with range validation
+- `scalars.createBoundedFloatScalar(name, min, max)` - Float with range validation
+- `scalars.createPatternStringScalar(name, pattern, message)` - String with regex pattern validation
+
+#### Creating Custom Scalars Manually
+
+You can also create custom scalars using `createValidatedScalar` directly:
 
 ```javascript
 const { GraphQLString, GraphQLInt } = require('graphql');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -2075,6 +2075,9 @@ export const addNoEndpointType = (gqltype) => {
 
 export { createValidatedScalar };
 
+export { default as validators } from './validators.js';
+export { default as scalars } from './scalars.js';
+
 const createArgsForQuery = (argTypes) => {
     const argsObject = {};
 

package/src/scalars.js

@@ -0,0 +1,188 @@
+import {
+  GraphQLString, GraphQLInt, GraphQLFloat,
+} from 'graphql';
+import { createValidatedScalar } from './index.js';
+
+/**
+ * Email scalar - validates email format
+ * Type name: Email_String
+ */
+export const EmailScalar = createValidatedScalar(
+  'Email',
+  'A valid email address',
+  GraphQLString,
+  (value) => {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!emailRegex.test(value)) {
+      throw new Error('Invalid email format');
+    }
+  },
+);
+
+/**
+ * URL scalar - validates URL format
+ * Type name: URL_String
+ */
+export const URLScalar = createValidatedScalar(
+  'URL',
+  'A valid URL',
+  GraphQLString,
+  (value) => {
+    try {
+      new URL(value);
+    } catch {
+      throw new Error('Invalid URL format');
+    }
+  },
+);
+
+/**
+ * PositiveInt scalar - validates positive integers
+ * Type name: PositiveInt_Int
+ */
+export const PositiveIntScalar = createValidatedScalar(
+  'PositiveInt',
+  'A positive integer',
+  GraphQLInt,
+  (value) => {
+    if (value <= 0) {
+      throw new Error('Value must be positive');
+    }
+  },
+);
+
+/**
+ * PositiveFloat scalar - validates positive floats
+ * Type name: PositiveFloat_Float
+ */
+export const PositiveFloatScalar = createValidatedScalar(
+  'PositiveFloat',
+  'A positive float',
+  GraphQLFloat,
+  (value) => {
+    if (value <= 0) {
+      throw new Error('Value must be positive');
+    }
+  },
+);
+
+/**
+ * Factory function to create a bounded string scalar
+ * @param {string} name - Name for the scalar
+ * @param {number} min - Minimum length
+ * @param {number} max - Maximum length
+ * @returns {GraphQLScalarType} A scalar type with length validation
+ */
+export const createBoundedStringScalar = (name, min, max) => {
+  return createValidatedScalar(
+    name,
+    `A string with length between ${min} and ${max} characters`,
+    GraphQLString,
+    (value) => {
+      if (typeof value !== 'string') {
+        throw new Error('Value must be a string');
+      }
+      if (min !== undefined && value.length < min) {
+        throw new Error(`String must be at least ${min} characters`);
+      }
+      if (max !== undefined && value.length > max) {
+        throw new Error(`String must be at most ${max} characters`);
+      }
+    },
+  );
+};
+
+/**
+ * Factory function to create a bounded integer scalar
+ * @param {string} name - Name for the scalar
+ * @param {number} min - Minimum value
+ * @param {number} max - Maximum value
+ * @returns {GraphQLScalarType} A scalar type with range validation
+ */
+export const createBoundedIntScalar = (name, min, max) => {
+  return createValidatedScalar(
+    name,
+    `An integer between ${min} and ${max}`,
+    GraphQLInt,
+    (value) => {
+      if (typeof value !== 'number' || isNaN(value)) {
+        throw new Error('Value must be a number');
+      }
+      if (min !== undefined && value < min) {
+        throw new Error(`Value must be at least ${min}`);
+      }
+      if (max !== undefined && value > max) {
+        throw new Error(`Value must be at most ${max}`);
+      }
+    },
+  );
+};
+
+/**
+ * Factory function to create a bounded float scalar
+ * @param {string} name - Name for the scalar
+ * @param {number} min - Minimum value
+ * @param {number} max - Maximum value
+ * @returns {GraphQLScalarType} A scalar type with range validation
+ */
+export const createBoundedFloatScalar = (name, min, max) => {
+  return createValidatedScalar(
+    name,
+    `A float between ${min} and ${max}`,
+    GraphQLFloat,
+    (value) => {
+      if (typeof value !== 'number' || isNaN(value)) {
+        throw new Error('Value must be a number');
+      }
+      if (min !== undefined && value < min) {
+        throw new Error(`Value must be at least ${min}`);
+      }
+      if (max !== undefined && value > max) {
+        throw new Error(`Value must be at most ${max}`);
+      }
+    },
+  );
+};
+
+/**
+ * Factory function to create a regex pattern string scalar
+ * @param {string} name - Name for the scalar
+ * @param {RegExp|string} pattern - Regex pattern to validate against
+ * @param {string} message - Error message if validation fails
+ * @returns {GraphQLScalarType} A scalar type with pattern validation
+ */
+export const createPatternStringScalar = (name, pattern, message) => {
+  const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+  const errorMessage = message || 'Value does not match required pattern';
+
+  return createValidatedScalar(
+    name,
+    `A string matching the pattern: ${pattern}`,
+    GraphQLString,
+    (value) => {
+      if (typeof value !== 'string') {
+        throw new Error('Value must be a string');
+      }
+      if (!regex.test(value)) {
+        throw new Error(errorMessage);
+      }
+    },
+  );
+};
+
+// Export all scalars as an object for convenience
+const scalars = {
+  // Pre-built scalars
+  EmailScalar,
+  URLScalar,
+  PositiveIntScalar,
+  PositiveFloatScalar,
+  // Factory functions
+  createBoundedStringScalar,
+  createBoundedIntScalar,
+  createBoundedFloatScalar,
+  createPatternStringScalar,
+};
+
+export default scalars;
+

package/src/validators.js

@@ -0,0 +1,250 @@
+import SimfinityError from './errors/simfinity.error.js';
+
+/**
+ * Creates a validation object that works for both 'save' (CREATE) and 'update' (UPDATE) operations.
+ * The validators will be applied to both operations.
+ * For CREATE operations, the value must be provided and valid.
+ * For UPDATE operations, undefined/null values are allowed (field might not be updated),
+ * but if a value is provided, it must be valid.
+ */
+const createValidator = (validatorFn, required = false) => {
+  // Validator for CREATE operations - value is required if required=true
+  const validateCreate = async (typeName, fieldName, value, session) => {
+    if (required && (value === null || value === undefined)) {
+      throw new SimfinityError(`${fieldName} is required`, 'VALIDATION_ERROR', 400);
+    }
+    if (value !== null && value !== undefined) {
+      await validatorFn(typeName, fieldName, value, session);
+    }
+  };
+
+  // Validator for UPDATE operations - value is optional
+  const validateUpdate = async (typeName, fieldName, value, session) => {
+    // Skip validation if value is not provided (field is not being updated)
+    if (value === null || value === undefined) {
+      return;
+    }
+    // If value is provided, validate it
+    await validatorFn(typeName, fieldName, value, session);
+  };
+
+  const validatorCreate = { validate: validateCreate };
+  const validatorUpdate = { validate: validateUpdate };
+  
+  // Return validations for both CREATE and UPDATE operations
+  // Also support 'save'/'update' for backward compatibility (though code uses CREATE/UPDATE)
+  return {
+    CREATE: [validatorCreate],
+    UPDATE: [validatorUpdate],
+    save: [validatorCreate], // For backward compatibility
+    update: [validatorUpdate], // For backward compatibility
+  };
+};
+
+/**
+ * String validators
+ */
+export const stringLength = (name, min, max) => {
+  return createValidator(async (typeName, fieldName, value) => {
+    if (typeof value !== 'string') {
+      throw new SimfinityError(`${name} must be a string`, 'VALIDATION_ERROR', 400);
+    }
+    
+    if (min !== undefined && value.length < min) {
+      throw new SimfinityError(`${name} must be at least ${min} characters`, 'VALIDATION_ERROR', 400);
+    }
+    
+    if (max !== undefined && value.length > max) {
+      throw new SimfinityError(`${name} must be at most ${max} characters`, 'VALIDATION_ERROR', 400);
+    }
+  }, true); // Required for CREATE operations
+};
+
+export const maxLength = (name, max) => {
+  return createValidator(async (typeName, fieldName, value) => {
+    if (typeof value !== 'string') {
+      throw new SimfinityError(`${name} must be a string`, 'VALIDATION_ERROR', 400);
+    }
+    
+    if (value.length > max) {
+      throw new SimfinityError(`${name} must be at most ${max} characters`, 'VALIDATION_ERROR', 400);
+    }
+  }, false); // Optional
+};
+
+export const pattern = (name, regex, message) => {
+  const regexObj = typeof regex === 'string' ? new RegExp(regex) : regex;
+  const errorMessage = message || `${name} format is invalid`;
+  
+  return createValidator(async (typeName, fieldName, value) => {
+    if (typeof value !== 'string') {
+      throw new SimfinityError(`${name} must be a string`, 'VALIDATION_ERROR', 400);
+    }
+    
+    if (!regexObj.test(value)) {
+      throw new SimfinityError(errorMessage, 'VALIDATION_ERROR', 400);
+    }
+  }, false); // Optional
+};
+
+export const email = () => {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  
+  return createValidator(async (typeName, fieldName, value) => {
+    if (typeof value !== 'string') {
+      throw new SimfinityError('Email must be a string', 'VALIDATION_ERROR', 400);
+    }
+    
+    if (!emailRegex.test(value)) {
+      throw new SimfinityError('Invalid email format', 'VALIDATION_ERROR', 400);
+    }
+  }, false); // Optional
+};
+
+export const url = () => {
+  return createValidator(async (typeName, fieldName, value) => {
+    if (typeof value !== 'string') {
+      throw new SimfinityError('URL must be a string', 'VALIDATION_ERROR', 400);
+    }
+    
+    try {
+      // Use URL constructor for better validation
+      new URL(value);
+    } catch (e) {
+        console.log('Invalid URL format', e);
+      throw new SimfinityError('Invalid URL format', 'VALIDATION_ERROR', 400);
+    }
+  }, false); // Optional
+};
+
+/**
+ * Number validators
+ */
+export const numberRange = (name, min, max) => {
+  return createValidator(async (typeName, fieldName, value) => {
+    if (typeof value !== 'number' || isNaN(value)) {
+      throw new SimfinityError(`${name} must be a number`, 'VALIDATION_ERROR', 400);
+    }
+    
+    if (min !== undefined && value < min) {
+      throw new SimfinityError(`${name} must be at least ${min}`, 'VALIDATION_ERROR', 400);
+    }
+    
+    if (max !== undefined && value > max) {
+      throw new SimfinityError(`${name} must be at most ${max}`, 'VALIDATION_ERROR', 400);
+    }
+  }, false); // Optional
+};
+
+export const positive = (name) => {
+  return createValidator(async (typeName, fieldName, value) => {
+    if (typeof value !== 'number' || isNaN(value)) {
+      throw new SimfinityError(`${name} must be a number`, 'VALIDATION_ERROR', 400);
+    }
+    
+    if (value <= 0) {
+      throw new SimfinityError(`${name} must be positive`, 'VALIDATION_ERROR', 400);
+    }
+  }, false); // Optional
+};
+
+/**
+ * Array validators
+ */
+export const arrayLength = (name, maxItems, itemValidator) => {
+  return createValidator(async (typeName, fieldName, value, session) => {
+    if (!Array.isArray(value)) {
+      throw new SimfinityError(`${name} must be an array`, 'VALIDATION_ERROR', 400);
+    }
+    
+    if (maxItems !== undefined && value.length > maxItems) {
+      throw new SimfinityError(`${name} must have at most ${maxItems} items`, 'VALIDATION_ERROR', 400);
+    }
+    
+    // If itemValidator is provided, validate each item
+    if (itemValidator && Array.isArray(itemValidator)) {
+      for (let i = 0; i < value.length; i++) {
+        for (const validator of itemValidator) {
+          await validator.validate(typeName, fieldName, value[i], session);
+        }
+      }
+    }
+  }, false); // Optional
+};
+
+/**
+ * Date validators
+ */
+export const dateFormat = (name, format) => {
+  return createValidator(async (typeName, fieldName, value) => {
+    // Handle Date objects, ISO strings, and timestamps
+    let date;
+    if (value instanceof Date) {
+      date = value;
+    } else if (typeof value === 'string') {
+      date = new Date(value);
+    } else if (typeof value === 'number') {
+      date = new Date(value);
+    } else {
+      throw new SimfinityError(`${name} must be a valid date`, 'VALIDATION_ERROR', 400);
+    }
+    
+    if (isNaN(date.getTime())) {
+      throw new SimfinityError(`${name} must be a valid date`, 'VALIDATION_ERROR', 400);
+    }
+    
+    // If format is provided, validate format
+    if (format && typeof value === 'string') {
+      // Simple format validation - can be enhanced
+      const formatRegex = /^\d{4}-\d{2}-\d{2}$/; // YYYY-MM-DD
+      if (format === 'YYYY-MM-DD' && !formatRegex.test(value)) {
+        throw new SimfinityError(`${name} must be in format ${format}`, 'VALIDATION_ERROR', 400);
+      }
+      // Add more format patterns as needed
+    }
+  }, false); // Optional
+};
+
+export const futureDate = (name) => {
+  return createValidator(async (typeName, fieldName, value) => {
+    let date;
+    if (value instanceof Date) {
+      date = value;
+    } else if (typeof value === 'string') {
+      date = new Date(value);
+    } else if (typeof value === 'number') {
+      date = new Date(value);
+    } else {
+      throw new SimfinityError(`${name} must be a valid date`, 'VALIDATION_ERROR', 400);
+    }
+    
+    if (isNaN(date.getTime())) {
+      throw new SimfinityError(`${name} must be a valid date`, 'VALIDATION_ERROR', 400);
+    }
+    
+    if (date <= new Date()) {
+      throw new SimfinityError(`${name} must be a future date`, 'VALIDATION_ERROR', 400);
+    }
+  }, false); // Optional
+};
+
+// Export all validators as an object
+const validators = {
+  // String validators
+  stringLength,
+  maxLength,
+  pattern,
+  email,
+  url,
+  // Number validators
+  numberRange,
+  positive,
+  // Array validators
+  arrayLength,
+  // Date validators
+  dateFormat,
+  futureDate,
+};
+
+export default validators;
+