@verisoft/core 19.0.0-rc001 → 20.1.0

package/.eslintrc.json

@@ -0,0 +1,43 @@
+{
+  "extends": ["../../../.eslintrc.base.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts"],
+      "extends": [
+        "plugin:@nx/angular",
+        "plugin:@angular-eslint/template/process-inline-templates"
+      ],
+      "rules": {
+        "@angular-eslint/directive-selector": [
+          "error",
+          {
+            "type": "attribute",
+            "prefix": "v",
+            "style": "camelCase"
+          }
+        ],
+        "@angular-eslint/component-selector": [
+          "error",
+          {
+            "type": "element",
+            "prefix": "v",
+            "style": "kebab-case"
+          }
+        ]
+      }
+    },
+    {
+      "files": ["*.html"],
+      "extends": ["plugin:@nx/angular-template"],
+      "rules": {}
+    },
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/dependency-checks": "error"
+      }
+    }
+  ]
+}

package/README.md

@@ -1,5 +1,289 @@
-# core
+# @verisoft/core
 
+Core utilities and HTTP services for Verisoft Angular applications, providing foundational functionality for data access, HTTP communication, and utility operations.
+
+## Installation
+
+```bash
+npm install @verisoft/core
+```
+
+## Features
+
+- **BaseHttpService**: Generic HTTP service with CRUD operations
+- **HTTP Models**: Type-safe request/response models
+- **Utility Functions**: Common operations for arrays, objects, dates, and data manipulation
+- **Storage Services**: Local storage abstraction
+- **Error Handling**: Centralized error provider service
+
+## Core Services
+
+### BaseHttpService
+
+Generic HTTP service providing standardized CRUD operations for REST APIs.
+
+```typescript
+import { Injectable } from '@angular/core';
+import { BaseHttpService } from '@verisoft/core';
+
+@Injectable({ providedIn: 'root' })
+export class UserService extends BaseHttpService<User> {
+  constructor() {
+    super('users'); // Base endpoint path
+  }
+}
+
+// Usage
+export class UserComponent {
+  constructor(private userService: UserService) {}
+
+  loadUsers() {
+    this.userService.fetchList({ page: 1, size: 10 })
+      .subscribe(page => {
+        console.log(page.data); // User[]
+        console.log(page.total); // Total count
+      });
+  }
+
+  getUser(id: number) {
+    this.userService.get(id)
+      .subscribe(user => console.log(user));
+  }
+
+  createUser(user: CreateUserDto) {
+    this.userService.post(user)
+      .subscribe(created => console.log(created));
+  }
+
+  updateUser(id: number, user: UpdateUserDto) {
+    this.userService.put(id, user)
+      .subscribe(updated => console.log(updated));
+  }
+
+  deleteUser(id: number) {
+    this.userService.delete(id)
+      .subscribe(() => console.log('Deleted'));
+  }
+}
+```
+
+### HTTP Models
+
+Type-safe models for API communication:
+
+```typescript
+import { RequestParams, Page, SortDirection } from '@verisoft/core';
+
+interface UserFilter {
+  name?: string;
+  email?: string;
+  active?: boolean;
+}
+
+// Request parameters with filtering and sorting
+const params: RequestParams<UserFilter> = {
+  page: 1,
+  size: 20,
+  filter: {
+    active: true,
+    name: 'John'
+  },
+  sort: {
+    field: 'createdAt',
+    direction: SortDirection.DESC
+  }
+};
+
+// Response pagination
+interface UserPage extends Page<User> {
+  data: User[];
+  total: number;
+  size: number;
+}
+```
+
+### Utility Functions
+
+Common utility operations for data manipulation:
+
+```typescript
+import { 
+  ArrayUtils, 
+  ObjectUtils, 
+  DateUtils, 
+  DataUtils, 
+  ClearUtils 
+} from '@verisoft/core';
+
+// Array utilities
+const uniqueItems = ArrayUtils.unique([1, 2, 2, 3]);
+const groupedData = ArrayUtils.groupBy(users, 'department');
+
+// Object utilities
+const merged = ObjectUtils.merge(obj1, obj2);
+const cloned = ObjectUtils.deepClone(originalObject);
+
+// Date utilities
+const formatted = DateUtils.format(new Date(), 'DD/MM/YYYY');
+const isValid = DateUtils.isValid('2023-12-31');
+
+// Data utilities
+const filtered = DataUtils.filterBy(items, 'status', 'active');
+const sorted = DataUtils.sortBy(items, 'name');
+
+// Clear utilities
+const cleaned = ClearUtils.removeEmpty(objectWithNulls);
+```
+
+### Storage Services
+
+Local storage abstraction with type safety:
+
+```typescript
+import { LocalStorageService } from '@verisoft/core';
+
+export class SettingsService {
+  constructor(private storage: LocalStorageService) {}
+
+  saveUserPreferences(prefs: UserPreferences) {
+    this.storage.setItem('userPrefs', prefs);
+  }
+
+  getUserPreferences(): UserPreferences | null {
+    return this.storage.getItem<UserPreferences>('userPrefs');
+  }
+
+  clearPreferences() {
+    this.storage.removeItem('userPrefs');
+  }
+}
+```
+
+### Error Handling
+
+Centralized error provider for consistent error management:
+
+```typescript
+import { ErrorProviderService } from '@verisoft/core';
+
+@Component({...})
+export class MyComponent {
+  constructor(private errorProvider: ErrorProviderService) {}
+
+  handleApiError(error: any) {
+    this.errorProvider.handleError(error);
+    // Automatically handles common HTTP errors
+  }
+}
+```
+
+## Configuration
+
+### Base URL Configuration
+
+Configure the base URL for HTTP services:
+
+```typescript
+import { BASE_URL_PATH } from '@verisoft/core';
+
+@NgModule({
+  providers: [
+    {
+      provide: BASE_URL_PATH,
+      useValue: 'https://api.example.com/v1'
+    }
+  ]
+})
+export class AppModule {}
+```
+
+### Service Configuration
+
+Customize BaseHttpService behavior:
+
+```typescript
+@Injectable()
+export class CustomUserService extends BaseHttpService<User> {
+  constructor() {
+    super('users', {
+      timeout: 10000,
+      retries: 3,
+      headers: {
+        'Custom-Header': 'value'
+      }
+    });
+  }
+
+  // Override default methods
+  protected override handleError(error: any) {
+    // Custom error handling
+    return super.handleError(error);
+  }
+}
+```
+
+## Advanced Usage
+
+### Custom Request Parameters
+
+Extend request parameters for specific needs:
+
+```typescript
+interface CustomRequestParams<T> extends RequestParams<T> {
+  includeDeleted?: boolean;
+  expand?: string[];
+}
+
+class ExtendedService extends BaseHttpService<MyEntity> {
+  fetchWithOptions(params: CustomRequestParams<MyFilter>) {
+    return this.httpClient.get<Page<MyEntity>>(
+      this.buildUrl('', params)
+    );
+  }
+}
+```
+
+### Response Transformation
+
+Transform API responses:
+
+```typescript
+class TransformingService extends BaseHttpService<User> {
+  fetchList(params: RequestParams<UserFilter>) {
+    return super.fetchList(params).pipe(
+      map(page => ({
+        ...page,
+        data: page.data.map(user => ({
+          ...user,
+          fullName: `${user.firstName} ${user.lastName}`
+        }))
+      }))
+    );
+  }
+}
+```
+
+## Best Practices
+
+1. **Extend BaseHttpService**: Create specific services for each entity
+2. **Use Type Safety**: Define proper interfaces for filters and DTOs
+3. **Handle Errors**: Implement proper error handling strategies
+4. **Cache Responses**: Consider implementing caching for frequently accessed data
+5. **Test Services**: Write unit tests for service methods
+
+## Dependencies
+
+- `@angular/common/http`
+- `rxjs`
+- `moment` (for date utilities)
+
+## Contributing
+
+This library is part of the Verisoft framework ecosystem. Follow the established patterns and ensure compatibility with other @verisoft packages.
+
+## Running unit tests
+
+Run `nx test core` to execute the unit tests.
 This library was generated with [Nx](https://nx.dev).
 
 ## Running unit tests

package/jest.config.ts

@@ -0,0 +1,22 @@
+/* eslint-disable */
+export default {
+  displayName: 'core',
+  preset: '../../../jest.preset.js',
+  setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
+  coverageDirectory: '../../../coverage/src/libs/core',
+  transform: {
+    '^.+\\.(ts|mjs|js|html)$': [
+      'jest-preset-angular',
+      {
+        tsconfig: '<rootDir>/tsconfig.spec.json',
+        stringifyContentPathRegex: '\\.(html|svg)$',
+      },
+    ],
+  },
+  transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
+  snapshotSerializers: [
+    'jest-preset-angular/build/serializers/no-ng-attributes',
+    'jest-preset-angular/build/serializers/ng-snapshot',
+    'jest-preset-angular/build/serializers/html-comment',
+  ],
+};

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../../dist/src/libs/core",
+  "lib": {
+    "entryFile": "src/index.ts"
+  }
+}

package/package.json

@@ -1,30 +1,13 @@
 {
   "name": "@verisoft/core",
-  "version": "19.0.0-rc001",
+  "version": "20.1.0",
   "sideEffects": false,
   "peerDependencies": {
-    "@angular/common": "19.2.9",
-    "@angular/core": "19.2.9",
-    "@angular/forms": "19.2.9",
-    "@ngx-translate/core": "^16.0.4",
+    "@angular/common": "~20.2.0",
+    "@angular/core": "~20.2.0",
+    "@angular/forms": "~20.2.0",
+    "@ngx-translate/core": "^17.0.0",
     "moment": "^2.30.1",
     "rxjs": "~7.8.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "module": "fesm2022/verisoft-core.mjs",
-  "typings": "index.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./index.d.ts",
-      "default": "./fesm2022/verisoft-core.mjs"
-    }
-  },
-  "dependencies": {
-    "tslib": "^2.3.0"
   }
-}
+}

package/project.json

@@ -0,0 +1,36 @@
+{
+  "name": "core",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "src/libs/core/src",
+  "prefix": "lib",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/angular:package",
+      "outputs": ["{workspaceRoot}/dist/{projectRoot}"],
+      "options": {
+        "project": "src/libs/core/ng-package.json"
+      },
+      "configurations": {
+        "production": {
+          "tsConfig": "src/libs/core/tsconfig.lib.prod.json"
+        },
+        "development": {
+          "tsConfig": "src/libs/core/tsconfig.lib.json"
+        }
+      },
+      "defaultConfiguration": "production"
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "src/libs/core/jest.config.ts"
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    }
+  }
+}

package/src/lib/index.ts

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

package/{lib/models/all-item.datasource.d.ts → src/lib/models/all-item.datasource.ts}

@@ -1,4 +1,5 @@
 import { Observable } from 'rxjs';
+
 export interface AllItemDatasource<T> {
-    getData$: () => Observable<T[]>;
+  getData$: () => Observable<T[]>
 }

package/src/lib/models/base-http.models.ts

@@ -0,0 +1,144 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { HttpParams, HttpResponse } from '@angular/common/http';
+import { InjectionToken } from '@angular/core';
+
+export const BASE_URL_PATH = new InjectionToken<string>('BASE_URL_PATH');
+
+export function requestParamsToHttpParams<T>(
+  requestParams: Partial<RequestParams<T>>,
+  httpParams: HttpParams = new HttpParams()
+): HttpParams {
+  if (requestParams.limit != undefined) {
+    httpParams = httpParams.append('limit', requestParams.limit.toString());
+  }
+
+  if (requestParams.offset != undefined) {
+    httpParams = httpParams.append('offset', requestParams.offset.toString());
+  }
+
+  if (requestParams.id != '' && requestParams.id != undefined) {
+    httpParams = httpParams.append('id', requestParams.id as any);
+  }
+
+  httpParams = getFilter(requestParams, httpParams);
+  httpParams = getSort(requestParams, httpParams);
+
+  return httpParams;
+}
+
+function getFilter<T>(
+  requestParams: Partial<RequestParams<any>>,
+  httpParams: HttpParams
+): HttpParams {
+  if (!requestParams.filter) {
+    return httpParams;
+  }
+  Object.keys(requestParams?.filter).forEach((key) => {
+    const value = requestParams.filter?.[key as keyof Partial<T>];
+    if (value != undefined && !(typeof value === 'string' && value.trim() === "")) {
+      if (Array.isArray(value)) {
+        value.forEach((valueItem: any) => {
+          httpParams = httpParams.append(
+            'Filter.' + key, valueItem
+          );
+        });
+      } else {
+        httpParams = httpParams.append('Filter.' + key, value);
+      }
+    }
+  });
+  return httpParams;
+}
+
+function getSort(
+  requestParams: Partial<RequestParams<any>>,
+  httpParams: HttpParams
+): HttpParams {
+  if (!requestParams.sort) {
+    return httpParams;
+  }
+
+  requestParams.sort?.forEach((sort) => {
+    httpParams = httpParams
+      .append('Sort.Field', sort.field)
+      .append('Sort.Direction', sort.direction);
+  });
+  return httpParams;
+}
+
+export function saveFile(response: HttpResponse<Blob>) {
+  const fileName = response.headers
+    .get('Content-Disposition')
+    ?.split(';')[1]
+    .split('=')[1];
+  const blob: Blob = response.body as Blob;
+  const a = document.createElement('a');
+  a.download = fileName ?? 'undefined';
+  a.href = window.URL.createObjectURL(blob);
+  a.click();
+}
+
+export enum SortDirection {
+  asc = 'asc',
+  desc = 'desc',
+}
+
+export declare type SortDirectionType = keyof typeof SortDirection;
+
+export declare interface Sort {
+  field: string;
+  direction: SortDirectionType;
+}
+
+export interface RequestParams<T> extends AllDataRequestParams<T> {
+  offset: number;
+  limit: number;
+  id?: string;
+}
+
+export interface AllDataRequestParams<T> {
+  filter?: Partial<T>;
+  sort?: Sort[];
+}
+
+export interface Page<T> {
+  data: T[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+export interface CustomExport<T> {
+  sortDefinition?: Sort;
+  filter?: Partial<T>;
+  columnsToExport: ColumnExportSpecification[];
+}
+
+export interface ColumnExportSpecification {
+  name: string;
+  header: string;
+}
+
+export const DEFAULT_SEARCH_LIMIT = 50;
+
+export const DEFAULT_SEARCH_PARAMS: RequestParams<any> = {
+  offset: 0,
+  limit: DEFAULT_SEARCH_LIMIT,
+  id: '',
+};
+
+export function normalizeRequest<T>(
+  request: Partial<RequestParams<T>>,
+  minLimit: number | undefined = undefined
+): RequestParams<T> {
+  return {
+    offset: request?.offset ?? 0,
+    limit: !request?.limit
+      ? DEFAULT_SEARCH_LIMIT
+      : minLimit && request.limit < minLimit
+      ? minLimit
+      : request.limit,
+    filter: request?.filter,
+    sort: request?.sort,
+  };
+}

package/src/lib/models/constants.ts

@@ -0,0 +1,8 @@
+import { LazyLoadEvent } from './event.models';
+
+export const DEFAULT_PAGE_SIZE = 50;
+
+export const DEFAULT_LAZYLOAD_OPTIONS: LazyLoadEvent = {
+  offset: 0,
+  limit: DEFAULT_PAGE_SIZE,
+};

package/src/lib/models/datasource.model.ts

@@ -0,0 +1,77 @@
+import { HttpClient } from '@angular/common/http';
+import { isObservable, map, Observable, of } from 'rxjs';
+import { BaseHttpService } from '../services/base-http.service';
+import { AllItemDatasource } from './all-item.datasource';
+import { Page, RequestParams } from './base-http.models';
+import { DEFAULT_PAGE_SIZE } from './constants';
+
+export type DatasourceType<T> =
+  | string
+  | Observable<T[]>
+  | Observable<Page<T>>
+  | BaseHttpService<T>
+  | T[]
+  | Page<T>
+  | AllItemDatasource<T>;
+
+export type DataSourceFunctionType<T> = (
+  requestParams: RequestParams<T>
+) => Observable<Page<T>>;
+
+export function convertDatasource<T>(
+  datasource: DatasourceType<T>,
+  basePath: string,
+  httpClient: HttpClient
+): DataSourceFunctionType<T> {
+  if (!datasource) {
+    throw new Error('Datasource is not defined');
+  }
+
+  if (typeof datasource === 'string') {
+    const service = new BaseHttpService<T>(httpClient, basePath, datasource);
+    return (requestParams: RequestParams<T>) =>
+      service.fetchList(requestParams);
+  }
+
+  if (datasource instanceof BaseHttpService) {
+    return (requestParams: RequestParams<T>) =>
+      datasource.fetchList(requestParams);
+  }
+
+  if (isObservable(datasource)) {
+    return () =>
+      (datasource as Observable<Page<T> | T[]>).pipe(map(convertArrayToPage));
+  }
+
+  const allItemDatasource = <AllItemDatasource<T>>datasource;
+  if (allItemDatasource.getData$) {
+    return () =>
+      allItemDatasource
+        .getData$()
+        .pipe(map((data) => convertArrayToPage(data)));
+  }
+
+  const page = <Page<T>>datasource;
+  if (page.data) {
+    return () => of(page);
+  }
+
+  if (Array.isArray(datasource)) {
+    return () => of(convertArrayToPage(datasource));
+  }
+
+  throw new Error('Datasource is not supported');
+}
+
+function convertArrayToPage<T>(data: Page<T> | T[]): Page<T> {
+  if (Array.isArray(data)) {
+    return {
+      data: data ?? [],
+      total: data?.length ?? 0,
+      limit: data?.length ?? DEFAULT_PAGE_SIZE,
+      offset: 0,
+    };
+  }
+
+  return data as Page<T>;
+}

package/src/lib/models/error-provider.model.ts

@@ -0,0 +1,20 @@
+import { InjectionToken } from '@angular/core';
+import { ValidationErrors } from '@angular/forms';
+import { Observable } from 'rxjs';
+
+export interface ErrorProvider {
+  mapError(errors: ValidationErrors): Observable<string | undefined>;
+  errors: Record<string, (value?: any) => string>;
+}
+
+export const ERROR_PROVIDER_TOKEN
+  = new InjectionToken<ErrorProvider>('ERROR_PROVIDER_TOKEN');
+
+export enum CustomValidationCodes {}
+
+export const ErrorMap: Record<string, (value?: any) => string> = {
+  required: () => `VALIDATIONS.REQUIRED`,
+  email: () => `VALIDATIONS.EMAIL`,
+  minLength: () => 'VALIDATIONS.MIN_LENGTH',
+  maxLength: () => 'VALIDATIONS.MAX_LENGTH',
+};