@cratis/arc 18.4.3 → 18.6.0

package/queries/for_QueryResult/when_asking_has_data/and_it_is_undefined.ts

@@ -17,7 +17,7 @@ describe("when asking has data and it is undefined", () => {
             totalItems: 0,
             totalPages: 0,
             page: 0,
-            items: 0
+            size: 0
         },
         validationResults: [],
         data:undefined

package/queries/for_WebSocketMessage/when_creating_messages.ts

@@ -0,0 +1,67 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { WebSocketMessage, WebSocketMessageType } from '../WebSocketMessage';
+
+describe('when creating a ping message', () => {
+    let timestamp: number;
+    let message: WebSocketMessage;
+
+    beforeEach(() => {
+        timestamp = Date.now();
+        message = {
+            type: WebSocketMessageType.Ping,
+            timestamp: timestamp
+        };
+    });
+
+    it('should have ping type', () => {
+        message.type.should.equal(WebSocketMessageType.Ping);
+    });
+
+    it('should have timestamp', () => {
+        message.timestamp!.should.equal(timestamp);
+    });
+});
+
+describe('when creating a pong message', () => {
+    let timestamp: number;
+    let message: WebSocketMessage;
+
+    beforeEach(() => {
+        timestamp = Date.now();
+        message = {
+            type: WebSocketMessageType.Pong,
+            timestamp: timestamp
+        };
+    });
+
+    it('should have pong type', () => {
+        message.type.should.equal(WebSocketMessageType.Pong);
+    });
+
+    it('should have timestamp', () => {
+        message.timestamp!.should.equal(timestamp);
+    });
+});
+
+describe('when creating a data message', () => {
+    let data: object;
+    let message: WebSocketMessage;
+
+    beforeEach(() => {
+        data = { test: 'value' };
+        message = {
+            type: WebSocketMessageType.Data,
+            data: data
+        };
+    });
+
+    it('should have data type', () => {
+        message.type.should.equal(WebSocketMessageType.Data);
+    });
+
+    it('should have data', () => {
+        message.data.should.equal(data);
+    });
+});

package/queries/index.ts

@@ -17,5 +17,7 @@ export * from './ObservableQueryFor';
 export * from './IObservableQueryConnection';
 export * from './ObservableQueryConnection';
 export * from './ObservableQuerySubscription';
+export * from './WebSocketMessage';
 export * from './IQueryProvider';
-export * from './QueryProvider';
+export * from './QueryProvider';
+export * from './QueryValidator';

package/validation/IValidationRule.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ValidationResult } from './ValidationResult';
+
+/**
+ * Defines a validation rule that can be applied to a property.
+ * @template T The type being validated.
+ */
+export interface IValidationRule<T> {
+    /**
+     * Validate the given value.
+     * @param instance The instance being validated.
+     * @param propertyName The name of the property being validated.
+     * @returns An array of validation results, empty if valid.
+     */
+    validate(instance: T, propertyName: string): ValidationResult[];
+}

package/validation/PropertyRule.ts

@@ -0,0 +1,59 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IValidationRule } from './IValidationRule';
+import { ValidationResult } from './ValidationResult';
+import { ValidationResultSeverity } from './ValidationResultSeverity';
+
+/**
+ * Base class for property-based validation rules.
+ * @template T The type being validated.
+ * @template TProperty The type of the property being validated.
+ */
+export abstract class PropertyRule<T, TProperty> implements IValidationRule<T> {
+    protected errorMessage: string;
+
+    /**
+     * Initializes a new instance of the {@link PropertyRule} class.
+     * @param propertyAccessor Function to access the property value from the instance.
+     * @param defaultErrorMessage The default error message if validation fails.
+     */
+    constructor(
+        protected readonly propertyAccessor: (instance: T) => TProperty,
+        defaultErrorMessage: string
+    ) {
+        this.errorMessage = defaultErrorMessage;
+    }
+
+    /**
+     * Set a custom error message for this rule.
+     * @param message The custom error message.
+     * @returns This rule instance for chaining.
+     */
+    withMessage(message: string): this {
+        this.errorMessage = message;
+        return this;
+    }
+
+    /** @inheritdoc */
+    validate(instance: T, propertyName: string): ValidationResult[] {
+        const value = this.propertyAccessor(instance);
+        if (!this.isValid(value, instance)) {
+            return [new ValidationResult(
+                ValidationResultSeverity.Error,
+                this.errorMessage.replace('{PropertyName}', propertyName),
+                [propertyName],
+                null
+            )];
+        }
+        return [];
+    }
+
+    /**
+     * Determine if the property value is valid.
+     * @param value The property value.
+     * @param instance The instance being validated.
+     * @returns True if valid, false otherwise.
+     */
+    protected abstract isValid(value: TProperty, instance: T): boolean;
+}

package/validation/PropertyValidator.ts

@@ -0,0 +1,51 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IValidationRule } from './IValidationRule';
+import { ValidationResult } from './ValidationResult';
+
+/**
+ * Represents a validator for a specific property.
+ * @template T The type being validated.
+ */
+export class PropertyValidator<T> {
+    private readonly _rules: IValidationRule<T>[] = [];
+
+    /**
+     * Initializes a new instance of the {@link PropertyValidator} class.
+     * @param propertyName The name of the property being validated.
+     */
+    constructor(readonly propertyName: string) {
+    }
+
+    /**
+     * Add a validation rule to this property validator.
+     * @param rule The rule to add.
+     */
+    addRule(rule: IValidationRule<T>): void {
+        this._rules.push(rule);
+    }
+
+    /**
+     * Validate the property value.
+     * @param instance The instance being validated.
+     * @returns An array of validation results, empty if valid.
+     */
+    validate(instance: T): ValidationResult[] {
+        const results: ValidationResult[] = [];
+        for (const rule of this._rules) {
+            const ruleResults = rule.validate(instance, this.propertyName);
+            results.push(...ruleResults);
+        }
+        return results;
+    }
+
+    /**
+     * Gets whether or not the property is valid.
+     * @param instance The instance being validated.
+     * @returns True if valid, false otherwise.
+     */
+    isValid(instance: T): boolean {
+        return this.validate(instance).length === 0;
+    }
+}

package/validation/RuleBuilder.ts

@@ -0,0 +1,49 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PropertyValidator } from './PropertyValidator';
+import { IValidationRule } from './IValidationRule';
+import { PropertyRule } from './PropertyRule';
+
+/**
+ * Represents a builder for creating validation rules for a property.
+ * @template T The type being validated.
+ * @template TProperty The type of the property being validated.
+ */
+export class RuleBuilder<T, TProperty> {
+    private lastRule?: IValidationRule<T>;
+
+    /**
+     * Initializes a new instance of the {@link RuleBuilder} class.
+     * @param propertyValidator The property validator to add rules to.
+     * @param _propertyAccessor Function to access the property value.
+     */
+    constructor(
+        private readonly propertyValidator: PropertyValidator<T>,
+        private readonly _propertyAccessor: (instance: T) => TProperty
+    ) {
+    }
+
+    /**
+     * Add a custom validation rule.
+     * @param rule The validation rule to add.
+     * @returns The rule builder for chaining.
+     */
+    addRule(rule: IValidationRule<T>): RuleBuilder<T, TProperty> {
+        this.propertyValidator.addRule(rule);
+        this.lastRule = rule;
+        return this;
+    }
+
+    /**
+     * Set a custom error message for the last added rule.
+     * @param message The custom error message.
+     * @returns The rule builder for chaining.
+     */
+    withMessage(message: string): RuleBuilder<T, TProperty> {
+        if (this.lastRule && this.lastRule instanceof PropertyRule) {
+            this.lastRule.withMessage(message);
+        }
+        return this;
+    }
+}

package/validation/RuleBuilderExtensions.ts

@@ -0,0 +1,176 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RuleBuilder } from './RuleBuilder';
+import { NotEmptyRule, NotNullRule } from './rules/NotEmptyRule';
+import { MinLengthRule, MaxLengthRule, LengthRule } from './rules/LengthRules';
+import { EmailRule } from './rules/EmailRule';
+import { RegexRule } from './rules/RegexRule';
+import { GreaterThanRule, GreaterThanOrEqualRule, LessThanRule, LessThanOrEqualRule } from './rules/ComparisonRules';
+
+/**
+ * Extension methods for {@link RuleBuilder} to add validation rules in a fluent manner.
+ */
+
+/**
+ * Add a rule that the property must not be empty (not null, undefined, empty string, or empty array).
+ * @template T The type being validated.
+ * @template TProperty The type of the property.
+ * @param this The rule builder instance.
+ * @returns The rule builder for chaining.
+ */
+export function notEmpty<T, TProperty>(this: RuleBuilder<T, TProperty>): RuleBuilder<T, TProperty> {
+    const propertyAccessor = (this as unknown as { _propertyAccessor: (instance: T) => TProperty })._propertyAccessor;
+    return this.addRule(new NotEmptyRule<T>(propertyAccessor));
+}
+
+/**
+ * Add a rule that the property must not be null or undefined.
+ * @template T The type being validated.
+ * @template TProperty The type of the property.
+ * @param this The rule builder instance.
+ * @returns The rule builder for chaining.
+ */
+export function notNull<T, TProperty>(this: RuleBuilder<T, TProperty>): RuleBuilder<T, TProperty> {
+    const propertyAccessor = (this as unknown as { _propertyAccessor: (instance: T) => TProperty })._propertyAccessor;
+    return this.addRule(new NotNullRule<T>(propertyAccessor));
+}
+
+/**
+ * Add a rule that the string property must have at least the specified length.
+ * @template T The type being validated.
+ * @param this The rule builder instance.
+ * @param length The minimum length.
+ * @returns The rule builder for chaining.
+ */
+export function minLength<T>(this: RuleBuilder<T, string>, length: number): RuleBuilder<T, string> {
+    const propertyAccessor = (this as unknown as { _propertyAccessor: (instance: T) => string })._propertyAccessor;
+    return this.addRule(new MinLengthRule<T>(propertyAccessor, length));
+}
+
+/**
+ * Add a rule that the string property must have at most the specified length.
+ * @template T The type being validated.
+ * @param this The rule builder instance.
+ * @param length The maximum length.
+ * @returns The rule builder for chaining.
+ */
+export function maxLength<T>(this: RuleBuilder<T, string>, length: number): RuleBuilder<T, string> {
+    const propertyAccessor = (this as unknown as { _propertyAccessor: (instance: T) => string })._propertyAccessor;
+    return this.addRule(new MaxLengthRule<T>(propertyAccessor, length));
+}
+
+/**
+ * Add a rule that the string property must have a length between min and max.
+ * @template T The type being validated.
+ * @param this The rule builder instance.
+ * @param min The minimum length.
+ * @param max The maximum length.
+ * @returns The rule builder for chaining.
+ */
+export function length<T>(this: RuleBuilder<T, string>, min: number, max: number): RuleBuilder<T, string> {
+    const propertyAccessor = (this as unknown as { _propertyAccessor: (instance: T) => string })._propertyAccessor;
+    return this.addRule(new LengthRule<T>(propertyAccessor, min, max));
+}
+
+/**
+ * Add a rule that the string property must be a valid email address.
+ * @template T The type being validated.
+ * @param this The rule builder instance.
+ * @returns The rule builder for chaining.
+ */
+export function emailAddress<T>(this: RuleBuilder<T, string>): RuleBuilder<T, string> {
+    const propertyAccessor = (this as unknown as { _propertyAccessor: (instance: T) => string })._propertyAccessor;
+    return this.addRule(new EmailRule<T>(propertyAccessor));
+}
+
+/**
+ * Add a rule that the string property must match the specified regular expression.
+ * @template T The type being validated.
+ * @param this The rule builder instance.
+ * @param pattern The regular expression pattern.
+ * @param errorMessage Optional error message.
+ * @returns The rule builder for chaining.
+ */
+export function matches<T>(this: RuleBuilder<T, string>, pattern: RegExp, errorMessage?: string): RuleBuilder<T, string> {
+    const propertyAccessor = (this as unknown as { _propertyAccessor: (instance: T) => string })._propertyAccessor;
+    return this.addRule(new RegexRule<T>(propertyAccessor, pattern, errorMessage));
+}
+
+/**
+ * Add a rule that the number property must be greater than the specified value.
+ * @template T The type being validated.
+ * @param this The rule builder instance.
+ * @param threshold The value to compare against.
+ * @returns The rule builder for chaining.
+ */
+export function greaterThan<T>(this: RuleBuilder<T, number>, threshold: number): RuleBuilder<T, number> {
+    const propertyAccessor = (this as unknown as { _propertyAccessor: (instance: T) => number })._propertyAccessor;
+    return this.addRule(new GreaterThanRule<T>(propertyAccessor, threshold));
+}
+
+/**
+ * Add a rule that the number property must be greater than or equal to the specified value.
+ * @template T The type being validated.
+ * @param this The rule builder instance.
+ * @param threshold The value to compare against.
+ * @returns The rule builder for chaining.
+ */
+export function greaterThanOrEqual<T>(this: RuleBuilder<T, number>, threshold: number): RuleBuilder<T, number> {
+    const propertyAccessor = (this as unknown as { _propertyAccessor: (instance: T) => number })._propertyAccessor;
+    return this.addRule(new GreaterThanOrEqualRule<T>(propertyAccessor, threshold));
+}
+
+/**
+ * Add a rule that the number property must be less than the specified value.
+ * @template T The type being validated.
+ * @param this The rule builder instance.
+ * @param threshold The value to compare against.
+ * @returns The rule builder for chaining.
+ */
+export function lessThan<T>(this: RuleBuilder<T, number>, threshold: number): RuleBuilder<T, number> {
+    const propertyAccessor = (this as unknown as { _propertyAccessor: (instance: T) => number })._propertyAccessor;
+    return this.addRule(new LessThanRule<T>(propertyAccessor, threshold));
+}
+
+/**
+ * Add a rule that the number property must be less than or equal to the specified value.
+ * @template T The type being validated.
+ * @param this The rule builder instance.
+ * @param threshold The value to compare against.
+ * @returns The rule builder for chaining.
+ */
+export function lessThanOrEqual<T>(this: RuleBuilder<T, number>, threshold: number): RuleBuilder<T, number> {
+    const propertyAccessor = (this as unknown as { _propertyAccessor: (instance: T) => number })._propertyAccessor;
+    return this.addRule(new LessThanOrEqualRule<T>(propertyAccessor, threshold));
+}
+
+// Add the extension methods to the RuleBuilder prototype
+RuleBuilder.prototype.notEmpty = notEmpty;
+RuleBuilder.prototype.notNull = notNull;
+(RuleBuilder.prototype as unknown as { minLength: typeof minLength }).minLength = minLength;
+(RuleBuilder.prototype as unknown as { maxLength: typeof maxLength }).maxLength = maxLength;
+(RuleBuilder.prototype as unknown as { length: typeof length }).length = length;
+(RuleBuilder.prototype as unknown as { emailAddress: typeof emailAddress }).emailAddress = emailAddress;
+(RuleBuilder.prototype as unknown as { matches: typeof matches }).matches = matches;
+(RuleBuilder.prototype as unknown as { greaterThan: typeof greaterThan }).greaterThan = greaterThan;
+(RuleBuilder.prototype as unknown as { greaterThanOrEqual: typeof greaterThanOrEqual }).greaterThanOrEqual = greaterThanOrEqual;
+(RuleBuilder.prototype as unknown as { lessThan: typeof lessThan }).lessThan = lessThan;
+(RuleBuilder.prototype as unknown as { lessThanOrEqual: typeof lessThanOrEqual }).lessThanOrEqual = lessThanOrEqual;
+
+// Extend the RuleBuilder interface to include these methods
+declare module './RuleBuilder' {
+    interface RuleBuilder<T, TProperty> {
+        notEmpty(): RuleBuilder<T, TProperty>;
+        notNull(): RuleBuilder<T, TProperty>;
+        minLength(length: number): RuleBuilder<T, TProperty>;
+        maxLength(length: number): RuleBuilder<T, TProperty>;
+        length(min: number, max: number): RuleBuilder<T, TProperty>;
+        emailAddress(): RuleBuilder<T, TProperty>;
+        matches(pattern: RegExp, errorMessage?: string): RuleBuilder<T, TProperty>;
+        greaterThan(threshold: number): RuleBuilder<T, TProperty>;
+        greaterThanOrEqual(threshold: number): RuleBuilder<T, TProperty>;
+        lessThan(threshold: number): RuleBuilder<T, TProperty>;
+        lessThanOrEqual(threshold: number): RuleBuilder<T, TProperty>;
+    }
+}

package/validation/Validator.ts

@@ -1,15 +1,85 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { ValidationResult } from './ValidationResult';
+import { PropertyValidator } from './PropertyValidator';
+import { RuleBuilder } from './RuleBuilder';
+
 /**
- * Represents a validator.
+ * Represents a validator for a type that builds validation rules programmatically.
+ * @template T The type being validated.
  */
-export class Validator {
+export class Validator<T = object> {
+    private readonly _propertyValidators = new Map<string, PropertyValidator<T>>();
+
+    /**
+     * Define validation rules for a property.
+     * @template TProperty The type of the property.
+     * @param propertyAccessor Function to access the property from the instance.
+     * @returns A rule builder for the property.
+     */
+    ruleFor<TProperty>(propertyAccessor: (instance: T) => TProperty): RuleBuilder<T, TProperty> {
+        const propertyName = this.getPropertyName(propertyAccessor);
+        let propertyValidator = this._propertyValidators.get(propertyName);
+        
+        if (!propertyValidator) {
+            propertyValidator = new PropertyValidator<T>(propertyName);
+            this._propertyValidators.set(propertyName, propertyValidator);
+        }
+
+        return new RuleBuilder<T, TProperty>(propertyValidator, propertyAccessor);
+    }
+
+    /**
+     * Validate an instance.
+     * @param instance The instance to validate.
+     * @returns An array of validation results, empty if valid.
+     */
+    validate(instance: T): ValidationResult[] {
+        const results: ValidationResult[] = [];
+        for (const propertyValidator of this._propertyValidators.values()) {
+            const propertyResults = propertyValidator.validate(instance);
+            results.push(...propertyResults);
+        }
+        return results;
+    }
 
     /**
-     * Gets whether or not is valid.
+     * Gets whether or not the instance is valid.
+     * @param instance The instance to validate.
+     * @returns True if valid, false otherwise.
      */
-    get isValid() {
+    get isValid(): boolean {
         return true;
     }
+
+    /**
+     * Gets whether or not a specific instance is valid.
+     * @param instance The instance to validate.
+     * @returns True if valid, false otherwise.
+     */
+    isValidFor(instance: T): boolean {
+        return this.validate(instance).length === 0;
+    }
+
+    private getPropertyName<TProperty>(propertyAccessor: (instance: T) => TProperty): string {
+        // Create a proxy to capture property access
+        const propertyNames: string[] = [];
+        const proxy = new Proxy({} as Record<string, unknown>, {
+            get(_target, prop) {
+                if (typeof prop === 'string') {
+                    propertyNames.push(prop);
+                }
+                return undefined;
+            }
+        });
+
+        try {
+            propertyAccessor(proxy as T);
+        } catch {
+            // Ignore errors - we're just capturing the property name
+        }
+
+        return propertyNames[0] || 'unknown';
+    }
 }

package/validation/for_Validator/when_defining_multiple_rules_for_same_property.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Validator } from '../Validator';
+import '../RuleBuilderExtensions';
+
+interface TestType {
+    name: string;
+}
+
+describe("when defining multiple rules for same property", () => {
+    let validator: Validator<TestType>;
+    let instance: TestType;
+    let results: ReturnType<typeof validator.validate>;
+
+    beforeEach(() => {
+        validator = new Validator<TestType>();
+        validator.ruleFor(t => t.name).notEmpty().minLength(3);
+        
+        instance = { name: 'ab' };
+    
+        results = validator.validate(instance);
+    });
+
+    it("should_return_one_validation_error", () => {
+        results.should.have.lengthOf(1);
+    });
+
+    it("should_have_error_for_min_length", () => {
+        results[0].message.should.include('3');
+    });
+});

package/validation/for_Validator/when_using_custom_error_message.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Validator } from '../Validator';
+import '../RuleBuilderExtensions';
+
+interface TestType {
+    email: string;
+}
+
+describe("when using custom error message", () => {
+    let validator: Validator<TestType>;
+    let instance: TestType;
+    let customMessage: string;
+    let results: ReturnType<typeof validator.validate>;
+
+    beforeEach(() => {
+        customMessage = 'Email is required';
+        validator = new Validator<TestType>();
+        validator.ruleFor(t => t.email).notEmpty().withMessage(customMessage);
+        
+        instance = { email: '' };
+    
+        results = validator.validate(instance);
+    });
+
+    it("should_use_custom_error_message", () => {
+        results[0].message.should.equal(customMessage);
+    });
+});

package/validation/for_Validator/when_validating/with_all_rules_passing.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Validator } from '../../Validator';
+import '../../RuleBuilderExtensions';
+
+interface TestType {
+    name: string;
+    age: number;
+}
+
+describe("when validating with all rules passing", () => {
+    let validator: Validator<TestType>;
+    let instance: TestType;
+    let results: ReturnType<typeof validator.validate>;
+
+    beforeEach(() => {
+        validator = new Validator<TestType>();
+        validator.ruleFor(t => t.name).notEmpty();
+        validator.ruleFor(t => t.age).greaterThanOrEqual(18);
+        
+        instance = { name: 'John', age: 25 };
+    
+        results = validator.validate(instance);
+    });
+
+    it("should_return_no_validation_errors", () => {
+        results.should.be.empty;
+    });
+
+    it("should_indicate_instance_is_valid", () => {
+        validator.isValidFor(instance).should.be.true;
+    });
+});

package/validation/for_Validator/when_validating/with_multiple_rules_failing.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Validator } from '../../Validator';
+import '../../RuleBuilderExtensions';
+
+interface TestType {
+    name: string;
+    age: number;
+}
+
+describe("when validating with multiple rules failing", () => {
+    let validator: Validator<TestType>;
+    let instance: TestType;
+    let results: ReturnType<typeof validator.validate>;
+
+    beforeEach(() => {
+        validator = new Validator<TestType>();
+        validator.ruleFor(t => t.name).notEmpty();
+        validator.ruleFor(t => t.age).greaterThanOrEqual(18);
+        
+        instance = { name: '', age: 15 };
+    
+        results = validator.validate(instance);
+    });
+
+    it("should_return_two_validation_errors", () => {
+        results.should.have.lengthOf(2);
+    });
+
+    it("should_have_error_for_name_property", () => {
+        results.some(r => r.members.includes('name')).should.be.true;
+    });
+
+    it("should_have_error_for_age_property", () => {
+        results.some(r => r.members.includes('age')).should.be.true;
+    });
+});