@intellegens/cornerstone-client 0.0.9999-alpha-9 → 0.0.9999-alpha-10

package/src/data/api/dto/read/ReadSelectedNestedCollectionCriteriaDto.ts

@@ -0,0 +1,25 @@
+import { ReadSelectedCollectionOperator, ReadSelectedSearchDefinitionDto } from '@data';
+
+/**
+ * Defines criteria for searching within a collection navigation property using quantifiers (Any/All).
+ *
+ * This DTO allows navigation into a collection property and applying search criteria
+ * with a quantifier to determine if any or all elements match.
+ */
+export type ReadSelectedNestedCollectionCriteriaDto<T, TPropertyName extends keyof T> = {
+  /**
+   * The name of the collection navigation property to navigate into.
+   */
+  propertyName: TPropertyName;
+
+  /**
+   * The quantifier operator determining whether any or all elements must match.
+   */
+  collectionOperator: ReadSelectedCollectionOperator;
+
+  /**
+   * The search criteria to apply to elements in the collection.
+   * Type should be ReadSelectedSearchDefinitionDto of the collection element type.
+   */
+  criteria: ReadSelectedSearchDefinitionDto<unknown>;
+};

package/src/data/api/dto/read/ReadSelectedNestedCriteriaDto.ts

@@ -0,0 +1,20 @@
+import {ReadSelectedSearchDefinitionDto} from '@data';
+
+/**
+ * Defines criteria for searching within a nested object property.
+ *
+ * This DTO allows navigation into a nested object property and applying search criteria
+ * to that nested object. The property name must refer to a navigation property (not a collection).
+ */
+export type ReadSelectedNestedCriteriaDto<T, TPropertyName extends keyof T> = {
+    /**
+     * The name of the navigation property to navigate into.
+     */
+    propertyName: TPropertyName;
+
+    /**
+     * The search criteria to apply to the nested object.
+     * Type should be ReadSelectedSearchDefinitionDto of the nested object type.
+     */
+    criteria: ReadSelectedSearchDefinitionDto<unknown>;
+};

package/src/data/api/dto/read/ReadSelectedOrderingDefinitionDto.ts

@@ -0,0 +1,8 @@
+import { ReadSelectedOrderingPropertyDefinitionDto } from '@data';
+
+/**
+ * Represents the ordering definition for a controller.
+ */
+export type ReadSelectedOrderingDefinitionDto = {
+  order: ReadSelectedOrderingPropertyDefinitionDto[];
+};

package/src/data/api/dto/read/ReadSelectedOrderingPropertyDefinitionDto.ts

@@ -0,0 +1,16 @@
+import { PropertyPathDto, ReadSelectedOrderingDirection } from '@data';
+
+/**
+ * Defines the ordering property for a controller.
+ */
+export type ReadSelectedOrderingPropertyDefinitionDto = {
+  /**
+   * Gets or sets the property path.
+   */
+  propertyPath: PropertyPathDto;
+
+  /**
+   * Gets or sets the ordering direction.
+   */
+  direction: ReadSelectedOrderingDirection;
+};

package/src/data/api/dto/read/ReadSelectedPaginationDefinitionDto.ts

@@ -0,0 +1,13 @@
+/**
+ * Defines the pagination parameters for a controller.
+ */
+export type ReadSelectedPaginationDefinitionDto = {
+  /**
+   * Pagination offset
+   */
+  skip: number;
+  /**
+   * Pagination limit
+   */
+  limit: number;
+};

package/src/data/api/dto/read/ReadSelectedSearchDefinitionDto.ts

@@ -0,0 +1,43 @@
+import {
+    ReadSelectedLogicalOperator,
+    ReadSelectedNestedCollectionCriteriaDto,
+    ReadSelectedNestedCriteriaDto,
+    ReadSelectedSearchPropertyDefinitionDto,
+} from '@data';
+
+/**
+ * Defines the search criteria for a controller using a recursive structure.
+ *
+ * This DTO supports complex search queries with:
+ * - Logical operators (AND/OR) to combine multiple criteria
+ * - Direct property value comparisons via `propertyCriteria`
+ * - Nested searches via `searches` for recursive query composition
+ * - Navigation into nested objects via `nestedCriteria`
+ * - Collection quantifier queries (Any/All) via `nestedCollectionCriteria`
+ */
+export type ReadSelectedSearchDefinitionDto<T> = {
+    /**
+     * The logical operator to combine all criteria at this level.
+     */
+    logicalOperator: ReadSelectedLogicalOperator;
+
+    /**
+     * Recursive nested search definitions combined with the logical operator.
+     */
+    searches?: ReadSelectedSearchDefinitionDto<T>[];
+
+    /**
+     * Direct property value comparison criteria.
+     */
+    propertyCriteria?: ReadSelectedSearchPropertyDefinitionDto<T, keyof T>[];
+
+    /**
+     * Criteria for searching within nested object properties.
+     */
+    nestedCriteria?: ReadSelectedNestedCriteriaDto<T, keyof T>[];
+
+    /**
+     * Criteria for searching within collection properties using Any/All quantifiers.
+     */
+    nestedCollectionCriteria?: ReadSelectedNestedCollectionCriteriaDto<T, keyof T>[];
+};

package/src/data/api/dto/read/ReadSelectedSearchPropertyDefinitionDto.ts

@@ -0,0 +1,186 @@
+import {ReadSelectedComparisonOperator, ReadSelectedPropertyType} from '@data';
+
+/**
+ * Defines a direct property value comparison criteria for searching.
+ *
+ * This DTO represents a leaf-level search criterion that compares a single property
+ * against a value using a comparison operator. For nested property searches, use
+ * `ReadSelectedNestedCriteriaDto` or `ReadSelectedNestedCollectionCriteriaDto`.
+ */
+export type ReadSelectedSearchPropertyDefinitionDto<T, TPropertyName extends keyof T> =
+    Partial_ReadSelectedSearchPropertyDefinition_IndependentProperties<T, TPropertyName>
+    &
+    Partial_ReadSelectedSearchPropertyDefinition_TypedValueProperty
+    &
+    Partial_ReadSelectedSearchPropertyDefinition_TypedComparisonOperators;
+
+/**
+ * Defines independent properties
+ */
+type Partial_ReadSelectedSearchPropertyDefinition_IndependentProperties<T, TPropertyName extends keyof T> = {
+    /**
+     * The name of the property to compare.
+     *
+     * This must be a direct property on the target type, not a nested property path.
+     * Use nested criteria DTOs for navigation.
+     */
+    propertyName: TPropertyName;
+    /**
+     * The comparison operator to use for the search.
+     */
+    comparisonOperator: ReadSelectedComparisonOperator;
+    /**
+     * The type of the property value being searched.
+     */
+    valueType: ReadSelectedPropertyType;
+    /**
+     * The value to compare against.
+     */
+    value: unknown;
+};
+
+/**
+ * Defines the dependence between the .valueType and the type of the .value properties
+ */
+type Partial_ReadSelectedSearchPropertyDefinition_TypedValueProperty =
+// Boolean
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType: ReadSelectedPropertyType.Bool;
+    /**
+     * The value to use for the search.
+     */
+    value: boolean;
+}
+    // Number
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType:
+        | ReadSelectedPropertyType.Int
+        | ReadSelectedPropertyType.Short
+        | ReadSelectedPropertyType.Long
+        | ReadSelectedPropertyType.Decimal
+        | ReadSelectedPropertyType.Double
+        | ReadSelectedPropertyType.Float;
+    /**
+     * The value to use for the search.
+     */
+    value: number;
+}
+    // String
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType: ReadSelectedPropertyType.String;
+    /**
+     * The value to use for the search.
+     */
+    value: string;
+}
+    // Temporal
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType:
+        | ReadSelectedPropertyType.DateTime
+        | ReadSelectedPropertyType.DateTimeOffset
+        | ReadSelectedPropertyType.TimeSpan
+        | ReadSelectedPropertyType.DateOnly
+        | ReadSelectedPropertyType.TimeOnly;
+    /**
+     * The value to use for the search.
+     */
+    value: string;
+};
+
+/**
+ * Defines the dependence between the .valueType and the type of the .comparisonOperator properties
+ */
+type Partial_ReadSelectedSearchPropertyDefinition_TypedComparisonOperators =
+// Boolean
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType: ReadSelectedPropertyType.Bool;
+
+    /**
+     * The comparison operator to use for the search.
+     */
+    comparisonOperator: ReadSelectedComparisonOperator.Equal | ReadSelectedComparisonOperator.NotEqual;
+}
+    // Number
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType:
+        | ReadSelectedPropertyType.Int
+        | ReadSelectedPropertyType.Short
+        | ReadSelectedPropertyType.Long
+        | ReadSelectedPropertyType.Decimal
+        | ReadSelectedPropertyType.Double
+        | ReadSelectedPropertyType.Float;
+
+    /**
+     * The comparison operator to use for the search.
+     */
+    comparisonOperator:
+        | ReadSelectedComparisonOperator.Equal
+        | ReadSelectedComparisonOperator.NotEqual
+        | ReadSelectedComparisonOperator.LessThan
+        | ReadSelectedComparisonOperator.LessOrEqual
+        | ReadSelectedComparisonOperator.GreaterThan
+        | ReadSelectedComparisonOperator.GreaterOrEqual;
+}
+    // String
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType: ReadSelectedPropertyType.String;
+
+    /**
+     * The comparison operator to use for the search.
+     */
+    comparisonOperator:
+        | ReadSelectedComparisonOperator.Equal
+        | ReadSelectedComparisonOperator.NotEqual
+        | ReadSelectedComparisonOperator.Contains
+        | ReadSelectedComparisonOperator.StartsWith
+        | ReadSelectedComparisonOperator.EndsWith
+        | ReadSelectedComparisonOperator.IContains
+        | ReadSelectedComparisonOperator.IStartsWith
+        | ReadSelectedComparisonOperator.IEndsWith
+        | ReadSelectedComparisonOperator.IEqual
+        | ReadSelectedComparisonOperator.INotEqual;
+}
+    // Temporal
+    | {
+    /**
+     * The type of the property value being searched.
+     */
+    valueType:
+        | ReadSelectedPropertyType.DateTime
+        | ReadSelectedPropertyType.DateTimeOffset
+        | ReadSelectedPropertyType.TimeSpan
+        | ReadSelectedPropertyType.DateOnly
+        | ReadSelectedPropertyType.TimeOnly;
+
+    /**
+     * The comparison operator to use for the search.
+     */
+    comparisonOperator:
+        | ReadSelectedComparisonOperator.Equal
+        | ReadSelectedComparisonOperator.NotEqual
+        | ReadSelectedComparisonOperator.LessThan
+        | ReadSelectedComparisonOperator.LessOrEqual
+        | ReadSelectedComparisonOperator.GreaterThan
+        | ReadSelectedComparisonOperator.GreaterOrEqual;
+};

package/src/data/api/dto/read/index.ts

@@ -0,0 +1,9 @@
+export * from './ReadMetadataDto';
+export * from './ReadSelectedSearchPropertyDefinitionDto';
+export * from './ReadSelectedNestedCriteriaDto';
+export * from './ReadSelectedNestedCollectionCriteriaDto';
+export * from './ReadSelectedOrderingDefinitionDto';
+export * from './ReadSelectedOrderingPropertyDefinitionDto';
+export * from './ReadSelectedPaginationDefinitionDto';
+export * from './ReadSelectedDefinitionDto';
+export * from './ReadSelectedSearchDefinitionDto';

package/src/data/api/dto/response/ApiErrorDto.ts

@@ -0,0 +1,21 @@
+import {EmptyMetadataDto, ErrorCode, ValidationFailedMetadataDto} from '@data';
+
+/**
+ * Default, empty metadata.
+ */
+export type ApiErrorDto<TMetadata extends ApiErrorMetadataDto = ApiErrorMetadataDto> = {
+  message: string;
+    details?: string;
+    traceId?: string;
+    timestamp?: string;
+} & TMetadata;
+
+export type ApiErrorMetadataDto =
+    | {
+    code: ErrorCode.ValidationFailed;
+    metadata: ValidationFailedMetadataDto;
+}
+    | {
+    code: Omit<number, ErrorCode.ValidationFailed>;
+    metadata: EmptyMetadataDto;
+};

package/src/data/api/dto/response/ApiErrorResponseDto.ts

@@ -0,0 +1,13 @@
+import {ApiErrorDto, ApiErrorMetadataDto} from '@data';
+
+/**
+ * Represents an API response containing an error and empty metadata.
+ */
+export type ApiErrorResponseDto<TErrorMetadata extends ApiErrorMetadataDto = ApiErrorMetadataDto> = {
+    ok: false;
+
+    /**
+     * The error object containing information about the error
+     */
+    error: ApiErrorDto<TErrorMetadata>;
+};

package/src/data/api/dto/response/ApiResponseDto.ts

@@ -0,0 +1,7 @@
+import {ApiErrorMetadataDto, ApiErrorResponseDto, ApiSuccessResponseDto} from '@/data';
+import {Result} from '@utils/result';
+
+export type ApiResponseDto<T, TMetadata extends object, TErrorMetadata extends ApiErrorMetadataDto = ApiErrorMetadataDto> = Result<
+    ApiSuccessResponseDto<T, TMetadata>,
+    ApiErrorResponseDto<TErrorMetadata>
+>;

package/src/data/api/dto/response/ApiSuccessResponseDto.ts

@@ -0,0 +1,13 @@
+/**
+ * Represents a successful API response containing a result and metadata.
+ *
+ * @template T The type of result
+ * @template TMetadata The type of metadata
+ * @property {T} result - The result returned
+ * @property {TMetadata} metadata - Metadata about the result
+ */
+export type ApiSuccessResponseDto<T, TMetadata> = {
+    ok: true;
+  result: T;
+  metadata: TMetadata;
+};

package/src/data/api/dto/response/MetadataDto.ts

@@ -0,0 +1,24 @@
+declare const __brand: unique symbol;
+
+/**
+ * Utility type for creating branded types that are nominally different but structurally identical.
+ * This enables compile-time type safety for values that would otherwise have the same runtime structure.
+ *
+ * @template T - The brand identifier string literal type
+ *
+ * @example
+ * ```typescript
+ * type UserId = Brand<'userId'>;
+ * type OrderId = Brand<'orderId'>;
+ *
+ * const userId: UserId = { [__brand]: 'userId' } as UserId;
+ * const orderId: OrderId = userId; // Type error! Different brands
+ * ```
+ */
+export type Brand<T extends string> = { [__brand]: T };
+
+/**
+ * Default, empty metadata.
+ */
+export type EmptyMetadataDto = Brand<'emptyMetadata'>;
+export type ValidationFailedMetadataDto = Brand<'validationFailedMetadata'>;

package/src/data/api/dto/response/index.ts

@@ -0,0 +1,5 @@
+export * from './ApiResponseDto';
+export * from './ApiSuccessResponseDto';
+export * from './ApiErrorDto';
+export * from './MetadataDto';
+export * from './ApiErrorResponseDto';

package/src/data/api/enum/index.ts

@@ -0,0 +1,2 @@
+export * from './response';
+export * from './read';

package/src/data/api/enum/read/ReadSelectedCollectionOperator.ts

@@ -0,0 +1,17 @@
+/**
+ * Represents the collection quantifier operators that can be used when searching collection properties.
+ * 
+ * The `Any` operator matches if at least one element in the collection satisfies the criteria.
+ * The `All` operator matches if all elements in the collection satisfy the criteria.
+ */
+export enum ReadSelectedCollectionOperator {
+  /**
+   * Matches if at least one element in the collection satisfies the criteria.
+   */
+  Any = 0,
+
+  /**
+   * Matches if all elements in the collection satisfy the criteria.
+   */
+  All = 1,
+}

package/src/data/api/enum/read/ReadSelectedComparisonOperator.ts

@@ -0,0 +1,96 @@
+/**
+ * Represents the basic comparison operators that can be used in a controller.
+ */
+export enum ReadSelectedComparisonOperator {
+  //#region Any type
+
+  /**
+   * Represents the equal comparison operator.
+   */
+  Equal = 0,
+
+  /**
+   * Represents the not equal comparison operator.
+   */
+  NotEqual = 1,
+
+  /**
+   * Represents the is null comparison operator.
+   */
+  IsNull = 2,
+
+  /**
+   * Represents the is not null comparison operator.
+   */
+  IsNotNull = 3,
+
+  //#endregion
+
+  //#region Number
+
+  /**
+   * Represents the less than comparison operator.
+   */
+  LessThan = 100,
+
+  /**
+   * Represents the less than or equal comparison operator.
+   */
+  LessOrEqual = 101,
+
+  /**
+   * Represents the greater than comparison operator.
+   */
+  GreaterThan = 102,
+
+  /**
+   * Represents the greater than or equal comparison operator.
+   */
+  GreaterOrEqual = 103,
+
+  //#endregion
+
+  //#region String
+
+  /**
+   * Represents the contains comparison operator.
+   */
+  Contains = 200,
+
+  /**
+   * Represents the starts with comparison operator.
+   */
+  StartsWith = 201,
+
+  /**
+   * Represents the ends with comparison operator.
+   */
+  EndsWith = 202,
+
+  /**
+   * Represents the contains comparison operator (case-insensitive).
+   */
+  IContains = 203,
+
+  /**
+   * Represents the starts with comparison operator (case-insensitive).
+   */
+  IStartsWith = 204,
+  
+  /**
+   * Represents the ends with comparison operator (case-insensitive).
+   */
+  IEndsWith = 205,
+
+  /**
+   * Represents the equal comparison operator (case-insensitive).
+   */
+  IEqual = 206,
+
+  /**
+   * Represents the not equal comparison operator (case-insensitive).
+   */
+  INotEqual = 207,
+
+  //#endregion
+}

package/src/data/api/enum/read/ReadSelectedLogicalOperator.ts

@@ -0,0 +1,16 @@
+/**
+ * Represents the logical operators that can be used in a controller.
+ * - The `And` operator combines multiple conditions, requiring all of them to be true.
+ * - The `Or` operator combines multiple conditions, requiring at least one of them to be true.
+ */
+export enum ReadSelectedLogicalOperator {
+  /**
+   * Represents the logical AND operator.
+   */
+  And = 0,
+
+  /**
+   * Represents the logical OR operator.
+   */
+  Or = 1,
+}

package/src/data/api/enum/read/ReadSelectedOrderingDirection.ts

@@ -0,0 +1,13 @@
+/**
+ * Represents options for ordering directions
+ */
+export enum ReadSelectedOrderingDirection {
+  /**
+   * Ascending ordering
+   */
+  Ascending = 0,
+  /**
+   * Descending ordering
+   */
+  Descending = 1,
+}

package/src/data/api/enum/read/ReadSelectedPropertyType.ts

@@ -0,0 +1,86 @@
+/**
+ * Represents the basic property types that can be used in a controller.
+ * - The ReadSelectedPropertyType enum defines the basic property types that can be used in a fetch controller. These types include boolean, integer, long, and string.
+ */
+export enum ReadSelectedPropertyType {
+  //#region Boolean
+
+  /**
+   * Represents a boolean property type.
+   */
+  Bool = 0,
+
+  //#endregion
+
+  //#region Number
+
+  /**
+   * Represents an integer property type.
+   */
+  Int = 100,
+
+  /**
+   * Represents a short property type.
+   */
+  Short = 101,
+
+  /**
+   * Represents a long property type.
+   */
+  Long = 102,
+
+  /**
+   * Represents a decimal property type.
+   */
+  Decimal = 103,
+
+  /**
+   * Represents a double property type.
+   */
+  Double = 104,
+
+  /**
+   * Represents a float property type.
+   */
+  Float = 105,
+
+  //#endregion
+
+  //#region string
+
+  /**
+   * Represents a string property type.
+   */
+  String = 200,
+
+  //#endregion
+
+  //#region Time
+
+  /**
+   * Represents a DateTime property type.
+   */
+  DateTime = 300,
+
+  /**
+   * Represents a DateTimeOffset property type.
+   */
+  DateTimeOffset = 301,
+
+  /**
+   * Represents a TimeSpan property type.
+   */
+  TimeSpan = 302,
+
+  /**
+   * Represents a DateOnly property type.
+   */
+  DateOnly = 303,
+
+  /**
+   * Represents a TimeOnly property type.
+   */
+  TimeOnly = 304,
+
+  //#endregion
+}

package/src/data/api/enum/read/index.ts

@@ -0,0 +1,5 @@
+export * from './ReadSelectedCollectionOperator';
+export * from './ReadSelectedComparisonOperator';
+export * from './ReadSelectedLogicalOperator';
+export * from './ReadSelectedOrderingDirection';
+export * from './ReadSelectedPropertyType';

package/src/data/api/enum/response/ErrorCode.ts

@@ -0,0 +1,13 @@
+/**
+ * Represents available error codes to be returned as part of the ApiResponse object
+ */
+export enum ErrorCode {
+    InternalServerError = 500,
+    NotFound = 404,
+    BadRequest = 400,
+    NotImplemented = 501,
+    Unauthorized = 401,
+    GatewayTimeout = 504,
+    ValidationFailed = 422,
+    UnknownError = 599,
+}

package/src/data/api/enum/response/index.ts

@@ -0,0 +1 @@
+export * from './ErrorCode';

package/src/data/api/index.ts

@@ -0,0 +1,3 @@
+export * from './interface';
+export * from './dto';
+export * from './enum';