@blueprint-ts/core 1.0.0

package/src/service/pagination/contracts/PaginatorLoadDataOptions.ts

@@ -0,0 +1,4 @@
+export interface PaginatorLoadDataOptions {
+  replace?: boolean
+  flush?: boolean
+}

package/src/service/pagination/contracts/ViewDriverContract.ts

@@ -0,0 +1,12 @@
+export interface ViewDriverContract<ResourceInterface> {
+  setData(data: ResourceInterface): void
+  setTotal(value: number): void
+  getData(): ResourceInterface
+  getCurrentPage(): number
+  setPage(value: number): void
+  setPageSize(value: number): void
+  getPageSize(): number
+  getLastPage(): number
+  getPages(): number[]
+  getTotal(): number
+}

package/src/service/pagination/contracts/ViewDriverFactoryContract.ts

@@ -0,0 +1,5 @@
+import { type ViewDriverContract } from './ViewDriverContract'
+
+export interface ViewDriverFactoryContract {
+  make<ResourceInterface>(page: number, size: number): ViewDriverContract<ResourceInterface[]>
+}

package/src/service/pagination/dataDrivers/ArrayDriver.ts

@@ -0,0 +1,28 @@
+import { type PaginationDataDriverContract, PaginationDataDto } from '../index'
+
+export class ArrayDriver<ResourceInterface> implements PaginationDataDriverContract<ResourceInterface[]> {
+  public constructor(protected data: ResourceInterface[]) {}
+
+  public get(page: number, size: number): Promise<PaginationDataDto<ResourceInterface[]>> {
+    return new Promise((resolve) => {
+      resolve(
+        new PaginationDataDto<ResourceInterface[]>(
+          this.data.slice(this.calculatedStart(page, size), this.calculatedEnd(page, size)),
+          this.data.length
+        )
+      )
+    })
+  }
+
+  public setData(data: ResourceInterface[]): void {
+    this.data = data
+  }
+
+  protected calculatedStart(currentPage: number, pageSize: number): number {
+    return (currentPage - 1) * pageSize
+  }
+
+  protected calculatedEnd(currentPage: number, pageSize: number): number {
+    return currentPage * pageSize
+  }
+}

package/src/service/pagination/dtos/PaginationDataDto.ts

@@ -0,0 +1,14 @@
+export class PaginationDataDto<ResourceInterface> {
+  public constructor(
+    protected data: ResourceInterface,
+    protected total: number
+  ) {}
+
+  public getData(): ResourceInterface {
+    return this.data
+  }
+
+  public getTotal(): number {
+    return this.total
+  }
+}

package/src/service/pagination/factories/VuePaginationDriverFactory.ts

@@ -0,0 +1,9 @@
+import { VuePaginationDriver } from '../frontendDrivers/VuePaginationDriver'
+import { type ViewDriverFactoryContract } from '../contracts/ViewDriverFactoryContract'
+import { type ViewDriverContract } from '../contracts/ViewDriverContract'
+
+export class VuePaginationDriverFactory implements ViewDriverFactoryContract {
+  public make<ResourceInterface>(pageNumber: number, pageSize: number): ViewDriverContract<ResourceInterface[]> {
+    return new VuePaginationDriver<ResourceInterface>(pageNumber, pageSize)
+  }
+}

package/src/service/pagination/frontendDrivers/VuePaginationDriver.ts

@@ -0,0 +1,61 @@
+import { computed, ref, type Ref, type ComputedRef } from 'vue'
+import { type ViewDriverContract } from '../contracts/ViewDriverContract'
+
+export class VuePaginationDriver<ResourceInterface> implements ViewDriverContract<ResourceInterface[]> {
+  protected dataRef: Ref<ResourceInterface[]>
+  protected currentPageRef: Ref<number>
+  protected pageSizeRef: Ref<number>
+  protected totalRef: Ref<number>
+  protected totalPagesComputed: ComputedRef<number>
+  protected pagesComputed: ComputedRef<number[]>
+
+  public constructor(pageNumber: number, pageSize: number) {
+    this.dataRef = ref([]) as Ref<ResourceInterface[]>
+    this.currentPageRef = ref<number>(pageNumber)
+    this.pageSizeRef = ref<number>(pageSize)
+    this.totalRef = ref<number>(0)
+
+    this.totalPagesComputed = computed(() => Math.ceil(this.totalRef.value / this.pageSizeRef.value))
+    this.pagesComputed = computed(() => Array.from({ length: this.totalPagesComputed.value }, (_, i) => i + 1))
+  }
+
+  public setData(data: ResourceInterface[]): void {
+    this.dataRef.value = data
+  }
+
+  public setTotal(value: number): void {
+    this.totalRef.value = value
+  }
+
+  public getData(): ResourceInterface[] {
+    return this.dataRef.value
+  }
+
+  public getCurrentPage(): number {
+    return this.currentPageRef.value
+  }
+
+  public setPage(value: number): void {
+    this.currentPageRef.value = value
+  }
+
+  public setPageSize(value: number): void {
+    this.pageSizeRef.value = value
+  }
+
+  public getPageSize(): number {
+    return this.pageSizeRef.value
+  }
+
+  public getLastPage(): number {
+    return this.totalPagesComputed.value
+  }
+
+  public getPages(): number[] {
+    return this.pagesComputed.value
+  }
+
+  public getTotal(): number {
+    return this.totalRef.value
+  }
+}

package/src/service/pagination/index.ts

@@ -0,0 +1,16 @@
+import { PaginationDataDto } from './dtos/PaginationDataDto'
+import { VuePaginationDriver } from './frontendDrivers/VuePaginationDriver'
+import { Paginator } from './Paginator'
+import { InfiniteScroller } from './InfiniteScroller'
+import { VuePaginationDriverFactory } from './factories/VuePaginationDriverFactory'
+import { type PaginateableRequestContract } from './contracts/PaginateableRequestContract'
+import { type PaginationResponseContract } from './contracts/PaginationResponseContract'
+import { type PaginationDataDriverContract } from './contracts/PaginationDataDriverContract'
+import { getDisplayablePages } from '../../helpers'
+import { ArrayDriver } from './dataDrivers/ArrayDriver'
+import { type ViewDriverContract } from './contracts/ViewDriverContract'
+import { type ViewDriverFactoryContract } from './contracts/ViewDriverFactoryContract'
+
+export { PaginationDataDto, VuePaginationDriver, Paginator, InfiniteScroller, VuePaginationDriverFactory, getDisplayablePages, ArrayDriver }
+
+export type { PaginationDataDriverContract, PaginationResponseContract, PaginateableRequestContract, ViewDriverContract, ViewDriverFactoryContract }

package/src/service/persistenceDrivers/LocalStorageDriver.ts

@@ -0,0 +1,22 @@
+import { type PersistenceDriver } from './types/PersistenceDriver'
+
+export class LocalStorageDriver implements PersistenceDriver {
+  public constructor(protected suffix?: string) {}
+
+  private storageKey(key: string): string {
+    return this.suffix ? `state_${key}_${this.suffix}` : `state_${key}`
+  }
+
+  get<T>(key: string): T | null {
+    const data = localStorage.getItem(this.storageKey(key))
+
+    return data ? JSON.parse(data) : null
+  }
+  set<T>(key: string, state: T): void {
+    localStorage.setItem(this.storageKey(key), JSON.stringify(state))
+  }
+
+  remove(key: string): void {
+    localStorage.removeItem(this.storageKey(key))
+  }
+}

package/src/service/persistenceDrivers/NonPersistentDriver.ts

@@ -0,0 +1,12 @@
+import { type PersistenceDriver } from './types/PersistenceDriver'
+
+/** Default driver: does not persist any data. */
+export class NonPersistentDriver implements PersistenceDriver {
+  get(): null {
+    return null
+  }
+
+  set(): void {}
+
+  remove(): void {}
+}

package/src/service/persistenceDrivers/SessionStorageDriver.ts

@@ -0,0 +1,22 @@
+import { type PersistenceDriver } from './types/PersistenceDriver'
+
+export class SessionStorageDriver implements PersistenceDriver {
+  public constructor(protected suffix?: string) {}
+
+  private storageKey(key: string): string {
+    return this.suffix ? `state_${key}_${this.suffix}` : `state_${key}`
+  }
+
+  get<T>(key: string): T | null {
+    const data = sessionStorage.getItem(this.storageKey(key))
+
+    return data ? JSON.parse(data) : null
+  }
+  set<T>(key: string, state: T): void {
+    sessionStorage.setItem(this.storageKey(key), JSON.stringify(state))
+  }
+
+  remove(key: string): void {
+    sessionStorage.removeItem(this.storageKey(key))
+  }
+}

package/src/service/persistenceDrivers/index.ts

@@ -0,0 +1,8 @@
+import { LocalStorageDriver } from './LocalStorageDriver'
+import { NonPersistentDriver } from './NonPersistentDriver'
+import { SessionStorageDriver } from './SessionStorageDriver'
+import { type PersistenceDriver } from './types/PersistenceDriver'
+
+export { LocalStorageDriver, NonPersistentDriver, SessionStorageDriver }
+
+export type { PersistenceDriver }

package/src/service/persistenceDrivers/types/PersistenceDriver.ts

@@ -0,0 +1,5 @@
+export interface PersistenceDriver {
+  get<T>(key: string): T | null
+  set<T>(key: string, state: T): void
+  remove(key: string): void
+}

package/src/service/requests/BaseRequest.ts

@@ -0,0 +1,197 @@
+import qs from 'qs'
+import { ErrorHandler } from './ErrorHandler'
+import { RequestEvents } from './RequestEvents.enum'
+import { RequestMethodEnum } from './RequestMethod.enum'
+import { BaseResponse } from './responses/BaseResponse'
+import { ResponseException } from './exceptions/ResponseException'
+import { type DriverConfigContract } from './contracts/DriverConfigContract'
+import { type BodyFactoryContract } from './contracts/BodyFactoryContract'
+import { type RequestLoaderContract } from './contracts/RequestLoaderContract'
+import { type RequestDriverContract } from './contracts/RequestDriverContract'
+import { type RequestLoaderFactoryContract } from './contracts/RequestLoaderFactoryContract'
+import { type BaseRequestContract, type EventHandlerCallback } from './contracts/BaseRequestContract'
+import { type HeadersContract } from './contracts/HeadersContract'
+import { type ResponseHandlerContract } from './drivers/contracts/ResponseHandlerContract'
+import { type ResponseContract } from './contracts/ResponseContract'
+import { mergeDeep } from '../../helpers'
+import { v4 as uuidv4 } from 'uuid'
+
+export abstract class BaseRequest<
+  RequestLoaderLoadingType,
+  ResponseErrorBody,
+  ResponseBodyInterface = undefined,
+  ResponseClass extends ResponseContract<ResponseBodyInterface> = BaseResponse<ResponseBodyInterface>,
+  RequestBodyInterface = undefined,
+  RequestParamsInterface extends object = object
+> implements BaseRequestContract<RequestLoaderLoadingType, RequestBodyInterface, ResponseClass, RequestParamsInterface> {
+  protected requestId: string = uuidv4()
+  protected params: RequestParamsInterface | undefined = undefined
+  protected requestBody: RequestBodyInterface | undefined = undefined
+  protected requestLoader: RequestLoaderContract<RequestLoaderLoadingType> | undefined = undefined
+  protected abortSignal: AbortSignal | undefined = undefined
+  /* @ts-expect-error Ignore generics */
+  protected events: { [key in RequestEvents]?: EventHandlerCallback[] } = {}
+
+  protected static defaultBaseUrl: string
+
+  protected static requestDriver: RequestDriverContract
+  protected static requestLoaderFactory: RequestLoaderFactoryContract<unknown>
+
+  public constructor() {
+    if (BaseRequest.requestLoaderFactory !== undefined) {
+      this.requestLoader = BaseRequest.requestLoaderFactory.make() as RequestLoaderContract<RequestLoaderLoadingType>
+    }
+  }
+
+  public static setRequestDriver(driver: RequestDriverContract) {
+    this.requestDriver = driver
+  }
+
+  public static setRequestLoaderFactory<T>(factory: RequestLoaderFactoryContract<T>): void {
+    this.requestLoaderFactory = factory
+  }
+
+  public static setDefaultBaseUrl(url: string) {
+    this.defaultBaseUrl = url
+  }
+
+  public setRequestLoader(loader: RequestLoaderContract<RequestLoaderLoadingType>): this {
+    this.requestLoader = loader
+
+    return this
+  }
+
+  public getRequestId(): string {
+    return this.requestId
+  }
+
+  public abstract method(): RequestMethodEnum
+
+  public abstract url(): URL | string
+
+  public setParams(params?: RequestParamsInterface): this {
+    this.params = params
+
+    return this
+  }
+
+  public withParams(params: RequestParamsInterface): this {
+    this.params = this.params === undefined ? params : (mergeDeep({}, this.params, params) as RequestParamsInterface)
+
+    return this
+  }
+
+  public getParams(): RequestParamsInterface | undefined {
+    return this.params
+  }
+
+  public setBody(requestBody: RequestBodyInterface): this {
+    this.requestBody = requestBody
+
+    return this
+  }
+
+  public getBody(): RequestBodyInterface | undefined {
+    return this.requestBody
+  }
+
+  public requestHeaders(): HeadersContract {
+    return {}
+  }
+
+  public buildUrl(): URL {
+    const url = this.params !== undefined && Object.keys(this.params).length === 0 ? this.url() : this.url() + '?' + qs.stringify(this.params)
+
+    return new URL(url, this.baseUrl() ?? BaseRequest.defaultBaseUrl)
+  }
+
+  public on<T>(event: RequestEvents, handler: EventHandlerCallback<T>): this {
+    if (!this.events[event]) {
+      this.events[event] = []
+    }
+
+    this.events[event].push(handler)
+
+    return this
+  }
+
+  protected dispatch<T>(event: RequestEvents, value: T) {
+    if (!this.events[event]) {
+      return
+    }
+
+    this.events[event].forEach((handler: EventHandlerCallback<T>) => handler(value))
+  }
+
+  public async send(): Promise<ResponseClass> {
+    this.dispatch<boolean>(RequestEvents.LOADING, true)
+
+    this.requestLoader?.setLoading(true)
+
+    const responseSkeleton = this.getResponse()
+
+    const requestBody = this.requestBody === undefined ? undefined : this.getRequestBodyFactory()?.make(this.requestBody)
+
+    return BaseRequest.requestDriver
+      .send(
+        this.buildUrl(),
+        this.method(),
+        {
+          Accept: responseSkeleton.getAcceptHeader(),
+          ...this.requestHeaders()
+        },
+        requestBody,
+        this.getConfig()
+      )
+      .then(async (responseHandler: ResponseHandlerContract) => {
+        await responseSkeleton.setResponse(responseHandler)
+
+        return responseSkeleton
+      })
+      .catch(async (error) => {
+        if (error instanceof ResponseException) {
+          const handler = new ErrorHandler<ResponseErrorBody>(error.getResponse())
+
+          await handler.handle()
+        }
+
+        console.error('HankIT-UI: Unknown error received.', error)
+
+        throw error
+      })
+      .finally(() => {
+        this.dispatch<boolean>(RequestEvents.LOADING, false)
+        this.requestLoader?.setLoading(false)
+      })
+  }
+
+  public isLoading(): RequestLoaderLoadingType {
+    if (!this.requestLoader) {
+      throw new Error('Request loader is not set.')
+    }
+
+    return this.requestLoader.isLoading()
+  }
+
+  public abstract getResponse(): ResponseClass
+
+  public getRequestBodyFactory(): BodyFactoryContract<RequestBodyInterface | undefined> | undefined {
+    return undefined
+  }
+
+  public setAbortSignal(signal: AbortSignal): this {
+    this.abortSignal = signal
+
+    return this
+  }
+
+  protected baseUrl(): undefined {
+    return undefined
+  }
+
+  protected getConfig(): DriverConfigContract | undefined {
+    return {
+      abortSignal: this.abortSignal
+    }
+  }
+}

package/src/service/requests/ErrorHandler.ts

@@ -0,0 +1,64 @@
+import { PageExpiredException } from './exceptions/PageExpiredException'
+import { NotFoundException } from './exceptions/NotFoundException'
+import { UnauthorizedException } from './exceptions/UnauthorizedException'
+import { ValidationException } from './exceptions/ValidationException'
+import { ResponseException } from './exceptions/ResponseException'
+import { NoResponseReceivedException } from './exceptions/NoResponseReceivedException'
+import { ServerErrorException } from './exceptions/ServerErrorException'
+import { type ResponseHandlerContract } from './drivers/contracts/ResponseHandlerContract'
+
+export type ErrorHandlerCallback = ((response: ResponseHandlerContract) => boolean | void) | undefined
+
+export class ErrorHandler<ResponseErrorBody> {
+  protected body: ResponseErrorBody | undefined = undefined
+  protected static handler: ErrorHandlerCallback = undefined
+
+  public constructor(protected response: ResponseHandlerContract) {
+    // Check if there is a global error handler set
+    if (ErrorHandler.handler !== undefined) {
+      // If handler returns false, we don't process the error further
+      if (ErrorHandler.handler(response) === false) {
+        console.debug('Skipping further error handling due to global handler returning false.')
+        return
+      }
+    }
+  }
+
+  public async handle() {
+    this.body = await this.response.json<ResponseErrorBody>()
+
+    if (this.body === undefined) {
+      throw new NoResponseReceivedException(this.response)
+    }
+
+    this.handleResponseError(this.response, this.body)
+  }
+
+  public static registerHandler(callback: ErrorHandlerCallback) {
+    ErrorHandler.handler = callback
+  }
+
+  protected handleResponseError(response: ResponseHandlerContract, body: ResponseErrorBody) {
+    if (response.getStatusCode() === 401) {
+      throw new UnauthorizedException<ResponseErrorBody>(response, body)
+    }
+
+    if (response.getStatusCode() === 404) {
+      throw new NotFoundException<ResponseErrorBody>(response, body)
+    }
+
+    if (response.getStatusCode() === 419) {
+      throw new PageExpiredException<ResponseErrorBody>(response, body)
+    }
+
+    if (response.getStatusCode() === 422) {
+      throw new ValidationException<ResponseErrorBody>(response, body)
+    }
+
+    if (response.getStatusCode() === 500) {
+      throw new ServerErrorException<ResponseErrorBody>(response, body)
+    }
+
+    throw new ResponseException(response)
+  }
+}

package/src/service/requests/RequestEvents.enum.ts

@@ -0,0 +1,3 @@
+export enum RequestEvents {
+  LOADING = 'loading'
+}

package/src/service/requests/RequestMethod.enum.ts

@@ -0,0 +1,8 @@
+export enum RequestMethodEnum {
+  GET = 'GET',
+  HEAD = 'HEAD',
+  PATCH = 'PATCH',
+  POST = 'POST',
+  PUT = 'PUT',
+  DELETE = 'DELETE'
+}

package/src/service/requests/bodies/FormDataBody.ts

@@ -0,0 +1,41 @@
+import { type BodyContract } from '../contracts/BodyContract'
+import { type HeadersContract } from '../contracts/HeadersContract'
+import { isObject } from '../../../helpers'
+
+export class FormDataBody<RequestBody> implements BodyContract {
+  protected data: FormData
+
+  public constructor(data: RequestBody) {
+    this.data = this.toFormData(data)
+  }
+
+  public getContent(): FormData {
+    return this.data
+  }
+
+  public getHeaders(): HeadersContract {
+    return {}
+  }
+
+  protected toFormData(data: RequestBody, form: FormData = new FormData(), namespace: string | null = null): FormData {
+    for (const property in data) {
+      if (Object.prototype.hasOwnProperty.call(data, property)) {
+        const formKey = namespace ? namespace + '[' + property + ']' : property
+
+        // if the property is an object, but not a File, use recursivity.
+        if (data[property] instanceof Date) {
+          form.append(formKey, data[property].toISOString())
+        } else if (isObject(data[property]) && !(data[property] instanceof File)) {
+          // @ts-expect-error Problem with property of object
+          this.toFormData(data[property], form, formKey)
+        } else if (data[property] instanceof File || typeof data[property] === 'string') {
+          form.append(formKey, data[property])
+        } else {
+          throw new Error('Unexpected value')
+        }
+      }
+    }
+
+    return form
+  }
+}

package/src/service/requests/bodies/JsonBody.ts

@@ -0,0 +1,16 @@
+import { type BodyContract } from '../contracts/BodyContract'
+import { type HeadersContract } from '../contracts/HeadersContract'
+
+export class JsonBody<RequestBody> implements BodyContract {
+  public constructor(protected data: RequestBody) {}
+
+  public getHeaders(): HeadersContract {
+    return {
+      'Content-Type': 'application/json'
+    }
+  }
+
+  public getContent(): string {
+    return JSON.stringify(this.data)
+  }
+}

package/src/service/requests/contracts/AbortableRequestContract.ts

@@ -0,0 +1,3 @@
+export interface AbortableRequestContract {
+  setSignal(): void
+}

package/src/service/requests/contracts/BaseRequestContract.ts

@@ -0,0 +1,36 @@
+import { RequestMethodEnum } from '../RequestMethod.enum'
+import { RequestEvents } from '../RequestEvents.enum'
+import { type BodyFactoryContract } from './BodyFactoryContract'
+import { type HeadersContract } from './HeadersContract'
+
+export type EventHandlerCallback<T> = (value: T) => void
+
+export interface BaseRequestContract<RequestLoaderLoadingType, RequestBodyInterface, ResponseClass, RequestParamsInterface extends object> {
+  method(): RequestMethodEnum
+
+  url(): URL | string
+
+  setParams(params?: RequestParamsInterface): this
+
+  withParams(params?: RequestParamsInterface): this
+
+  getParams(): RequestParamsInterface | undefined
+
+  setBody(requestBody: RequestBodyInterface | undefined): this
+
+  requestHeaders(): HeadersContract
+
+  buildUrl(): URL
+
+  on<T>(event: RequestEvents, handler: EventHandlerCallback<T>): this
+
+  send(): Promise<ResponseClass>
+
+  isLoading(): RequestLoaderLoadingType
+
+  getRequestBodyFactory(): BodyFactoryContract<RequestBodyInterface> | undefined
+
+  getResponse(): ResponseClass
+
+  setAbortSignal(signal: AbortSignal): this
+}

package/src/service/requests/contracts/BodyContract.ts

@@ -0,0 +1,7 @@
+import { type HeadersContract } from './HeadersContract'
+
+export interface BodyContract {
+  getContent(): string | FormData
+
+  getHeaders(): HeadersContract
+}

package/src/service/requests/contracts/BodyFactoryContract.ts

@@ -0,0 +1,5 @@
+import { type BodyContract } from './BodyContract'
+
+export interface BodyFactoryContract<RequestBodyInterface> {
+  make(body: RequestBodyInterface): BodyContract
+}

package/src/service/requests/contracts/DriverConfigContract.ts

@@ -0,0 +1,7 @@
+import { type HeadersContract } from './HeadersContract'
+
+export interface DriverConfigContract {
+  corsWithCredentials?: boolean | undefined
+  abortSignal?: AbortSignal | undefined
+  headers?: HeadersContract | undefined
+}

package/src/service/requests/contracts/HeadersContract.ts

@@ -0,0 +1,5 @@
+export type HeaderValue = string | (() => string)
+
+export interface HeadersContract {
+  [key: string]: HeaderValue
+}

package/src/service/requests/contracts/RequestDriverContract.ts

@@ -0,0 +1,15 @@
+import { RequestMethodEnum } from '../RequestMethod.enum'
+import { type HeadersContract } from './HeadersContract'
+import { type BodyContract } from './BodyContract'
+import { type ResponseHandlerContract } from '../drivers/contracts/ResponseHandlerContract'
+import { type DriverConfigContract } from './DriverConfigContract'
+
+export interface RequestDriverContract {
+  send(
+    url: URL | string,
+    method: RequestMethodEnum,
+    headers: HeadersContract,
+    body?: BodyContract,
+    requestConfig?: DriverConfigContract
+  ): Promise<ResponseHandlerContract>
+}

package/src/service/requests/contracts/RequestLoaderContract.ts

@@ -0,0 +1,5 @@
+export interface RequestLoaderContract<T> {
+  isLoading(): T
+
+  setLoading(value: boolean): void
+}