@blueprint-ts/core 1.0.0

package/src/vue/state/State.ts

@@ -0,0 +1,391 @@
+import { debounce } from 'lodash-es'
+import { type PersistenceDriver } from '../../service/persistenceDrivers'
+import { NonPersistentDriver } from '../../service/persistenceDrivers'
+import { computed, ref, type Ref, watch, reactive } from 'vue'
+
+export interface StateOptions {
+  persist?: boolean
+  persistSuffix?: string
+}
+
+// Generic type for change handlers
+type ChangeHandler<T> = (val: T, oldVal: T) => void
+
+// Type for accessing nested properties with dot notation
+type PathValue<T, P extends string> = P extends keyof T
+  ? T[P]
+  : P extends `${infer K}.${infer Rest}`
+    ? K extends keyof T
+      ? T[K] extends Record<string, unknown>
+        ? PathValue<T[K], Rest>
+        : never
+      : never
+    : never
+
+// Helper type to get all possible paths in an object
+type PathsToStringProps<T> = T extends object ? { [K in keyof T]: K extends string ? K | `${K}.${PathsToStringProps<T[K]>}` : never }[keyof T] : never
+
+// Union type of all possible dot-notation paths in T
+type Path<T> = keyof T | PathsToStringProps<T>
+
+export abstract class State<T extends object> {
+  private readonly properties: { [K in keyof T]: Ref<T[K]> }
+  private readonly _initial: T
+  private readonly _persist: boolean
+  private readonly _persistKey: string
+  private _driver: PersistenceDriver
+  private _stateProxy: T | null = null
+  private _watchStopFunctions: Map<string, () => void> = new Map()
+  private _resetHandlers: Map<string, (() => void)[]> = new Map()
+
+  protected constructor(initial: T, options?: StateOptions) {
+    this._initial = initial
+    this._persist = !!options?.persist
+    const className = this.constructor.name
+    this._persistKey = className + (options?.persistSuffix ? `_${options.persistSuffix}` : '')
+    this._driver = this.getPersistenceDriver()
+
+    // --- Robust persistence load: invalidate if schema changed ---
+    let loaded: T | null = null
+    if (this._persist) {
+      loaded = this._driver.get<T>(this._persistKey)
+      if (loaded) {
+        const initialKeys = Object.keys(initial).sort()
+        const loadedKeys = Object.keys(loaded).sort()
+        const sameKeys = initialKeys.length === loadedKeys.length && initialKeys.every((k, i) => k === loadedKeys[i])
+        if (!sameKeys) {
+          // Schema mismatch: remove stale/corrupt data, use fresh
+          this._driver.remove(this._persistKey)
+          loaded = null
+        }
+      }
+    }
+
+    // Use the valid loaded state, or fallback to initial
+    const base = loaded ?? initial
+    this.properties = {} as { [K in keyof T]: Ref<T[K]> }
+    const keys = Object.keys(base) as Array<keyof T>
+
+    for (const k of keys) {
+      // Use Vue's reactive for objects and arrays
+      let value = (base as T)[k]
+      if (typeof value === 'object' && value !== null) {
+        value = reactive(this.deepClone(value)) as T[typeof k]
+      }
+
+      const _ref = ref(value) as Ref<T[typeof k]>
+
+      this.properties[k] = computed({
+        get: () => _ref.value,
+        set: (val) => {
+          // Make objects and arrays reactive
+          if (typeof val === 'object' && val !== null) {
+            _ref.value = reactive(this.deepClone(val)) as T[typeof k]
+          } else {
+            _ref.value = val
+          }
+
+          if (this._persist) {
+            this._driver.set(this._persistKey, this.export())
+          }
+        }
+      }) as Ref<T[typeof k]>
+    }
+  }
+
+  /**
+   * Safe deep clone that preserves types
+   */
+  private deepClone<V>(value: V): V {
+    if (value === null || value === undefined) return value
+    if (typeof value !== 'object') return value
+
+    return JSON.parse(JSON.stringify(value)) as V
+  }
+
+  /**
+   * Get a proxy to the state that allows direct property access and setting
+   * without using .value
+   */
+  public get state(): T {
+    if (!this._stateProxy) {
+      this._stateProxy = new Proxy({} as T, {
+        get: (_, prop: string | symbol) => {
+          if (typeof prop === 'symbol' || prop === 'toJSON') {
+            return undefined
+          }
+
+          const key = prop as keyof T
+          if (key in this.properties) {
+            return this.properties[key].value
+          }
+
+          return undefined
+        },
+        set: (_, prop: string | symbol, value) => {
+          if (typeof prop === 'symbol') {
+            return false
+          }
+
+          const key = prop as keyof T
+          if (key in this.properties) {
+            this.properties[key].value = value
+          }
+
+          return true
+        }
+      })
+    }
+
+    return this._stateProxy
+  }
+
+  /**
+   * Add a subscription to specific properties or nested properties
+   * @param paths Path(s) to the property. Can be:
+   *              - A single path (top-level key or nested with dot notation)
+   *              - An array of paths to watch (triggers when any changes)
+   * @param handler Function to call when the property changes
+   * @param options Optional configuration for debounce and executeOnReset
+   * @returns A function to remove the subscription
+   */
+  public subscribe<P extends Path<T>>(
+    paths: P,
+    handler: ChangeHandler<PathValue<T, P & string>>,
+    options?: { debounce?: number; executeOnReset?: boolean }
+  ): () => void
+  public subscribe<P extends Path<T>>(
+    paths: P[],
+    handler: (changedPath: P, state: T) => void,
+    options?: { debounce?: number; executeOnReset?: boolean }
+  ): () => void
+  public subscribe<P extends Path<T>>(
+    paths: P | P[],
+    handler: ChangeHandler<PathValue<T, P & string>> | ((changedPath: P, state: T) => void),
+    options?: { debounce?: number; executeOnReset?: boolean }
+  ): () => void {
+    // Keep track of all watchers for cleanup
+    const stopFunctions: (() => void)[] = []
+    const resetHandlers: (() => void)[] = []
+
+    // If paths is an array, register handlers for each path
+    if (Array.isArray(paths)) {
+      for (const path of paths) {
+        // For arrays, we expect the handler to have the signature (changedPath, state) => void
+        const pathHandler = () => {
+          ;(handler as (changedPath: P, state: T) => void)(path, this.export())
+        }
+
+        // Store reset handler if needed
+        if (options?.executeOnReset) {
+          resetHandlers.push(pathHandler)
+        }
+
+        // Register handler for this individual path
+        const stop = this.setupWatcher(path as string, pathHandler, options)
+        stopFunctions.push(stop)
+      }
+    } else {
+      const pathHandler = handler as ChangeHandler<unknown>
+
+      // Store reset handler if needed
+      if (options?.executeOnReset) {
+        resetHandlers.push(() => pathHandler(undefined, undefined))
+      }
+
+      // For single paths, register directly with the provided handler
+      const stop = this.setupWatcher(paths as string, pathHandler, options)
+      stopFunctions.push(stop)
+    }
+
+    // Store reset handlers for later execution
+    if (resetHandlers.length > 0) {
+      const resetId = Math.random().toString(36)
+      this._resetHandlers.set(resetId, resetHandlers)
+
+      stopFunctions.push(() => {
+        this._resetHandlers.delete(resetId)
+      })
+    }
+
+    // Return a function that stops all watchers
+    return () => stopFunctions.forEach((stop) => stop())
+  }
+
+  /**
+   * Internal method to set up a watcher for a specific path
+   */
+  private setupWatcher(
+    path: string,
+    handler: (newVal?: unknown, oldVal?: unknown) => void,
+    options?: { debounce?: number; executeOnReset?: boolean }
+  ): () => void {
+    const pathParts = path.split('.')
+    const debouncedHandler = options?.debounce && options.debounce > 0 ? debounce(handler, options.debounce) : undefined
+
+    const effectiveHandler = debouncedHandler || handler
+
+    // For top-level properties
+    if (pathParts.length === 1 && path in this.properties) {
+      const key = path as keyof T
+
+      // Set up watcher for this property
+      const stopWatch = watch(
+        () => this.properties[key].value,
+        (newVal, oldVal) => {
+          if (!this.isEqual(newVal, oldVal)) {
+            effectiveHandler(newVal, oldVal)
+          }
+        },
+        { deep: true }
+      )
+
+      // Save stop function for cleanup
+      const watchId = `prop:${String(key)}`
+      this._watchStopFunctions.set(watchId, stopWatch)
+
+      return () => {
+        if (this._watchStopFunctions.has(watchId)) {
+          this._watchStopFunctions.get(watchId)!()
+          this._watchStopFunctions.delete(watchId)
+        }
+      }
+    }
+
+    // For nested properties
+    const topLevelKey = pathParts[0] as keyof T
+
+    if (topLevelKey in this.properties) {
+      // Create a nested property getter
+      const getter = () => {
+        let obj = this.properties[topLevelKey].value
+
+        for (let i = 1; i < pathParts.length; i++) {
+          if (!obj || typeof obj !== 'object') return undefined
+          obj = (obj as any)[pathParts[i]]
+        }
+
+        return obj
+      }
+
+      // Set up watcher for this nested property
+      const stopWatch = watch(
+        getter,
+        (newVal, oldVal) => {
+          if (!this.isEqual(newVal, oldVal)) {
+            effectiveHandler(newVal, oldVal)
+          }
+        },
+        { deep: true }
+      )
+
+      // Save stop function for cleanup
+      const watchId = `nested:${String(path)}`
+      this._watchStopFunctions.set(watchId, stopWatch)
+
+      return () => {
+        if (this._watchStopFunctions.has(watchId)) {
+          this._watchStopFunctions.get(watchId)!()
+          this._watchStopFunctions.delete(watchId)
+        }
+      }
+    }
+
+    // If path doesn't exist, return a no-op
+    return () => {}
+  }
+
+  /**
+   * Simple deep equality check
+   */
+  private isEqual(a: unknown, b: unknown): boolean {
+    if (a === b) return true
+
+    if (a === null || b === null) return false
+    if (a === undefined || b === undefined) return false
+
+    if (typeof a !== typeof b) return false
+
+    if (typeof a === 'object' && typeof b === 'object') {
+      const aArray = Array.isArray(a)
+      const bArray = Array.isArray(b)
+
+      if (aArray !== bArray) return false
+
+      if (aArray && bArray) {
+        const arrayA = a as unknown[]
+        const arrayB = b as unknown[]
+        if (arrayA.length !== arrayB.length) return false
+        return arrayA.every((val, i) => this.isEqual(val, arrayB[i]))
+      }
+
+      const objA = a as Record<string, unknown>
+      const objB = b as Record<string, unknown>
+
+      const keysA = Object.keys(objA).sort()
+      const keysB = Object.keys(objB).sort()
+
+      if (keysA.length !== keysB.length) return false
+      if (!keysA.every((k, i) => k === keysB[i])) return false
+
+      return keysA.every((k) => this.isEqual(objA[k], objB[k]))
+    }
+
+    return false
+  }
+
+  protected getPersistenceDriver(): PersistenceDriver {
+    return new NonPersistentDriver()
+  }
+
+  public export(): T {
+    const out = {} as T
+    for (const k in this.properties) {
+      const key = k as keyof T
+      out[key] = this.deepClone(this.properties[key].value)
+    }
+    return out
+  }
+
+  public import(data: Partial<T>): void {
+    for (const k in data) {
+      if (k in this.properties) {
+        const key = k as keyof T
+        this.properties[key].value = data[key] as T[typeof key]
+      }
+    }
+    if (this._persist) {
+      this._driver.set(this._persistKey, this.export())
+    }
+  }
+
+  public reset(): void {
+    this.import(this._initial)
+
+    // Execute reset handlers
+    for (const handlers of this._resetHandlers.values()) {
+      for (const handler of handlers) {
+        handler()
+      }
+    }
+  }
+
+  public get persistKey(): string {
+    return this._persistKey
+  }
+
+  /**
+   * Clean up all watchers when the state is no longer needed
+   */
+  public destroy(): void {
+    // Stop all watchers
+    for (const stopFn of this._watchStopFunctions.values()) {
+      stopFn()
+    }
+    this._watchStopFunctions.clear()
+    this._resetHandlers.clear()
+
+    // Remove reference to proxy
+    this._stateProxy = null
+  }
+}

package/src/vue/state/index.ts

@@ -0,0 +1,3 @@
+import { State } from './State'
+
+export { State }

package/tests/service/helpers/mergeDeep.test.ts

@@ -0,0 +1,53 @@
+import { mergeDeep } from '../../../src/helpers'
+import { describe, it, expect } from 'vitest';
+
+describe('mergeDeep', () => {
+  it('should merge nested objects and replace primitive values', () => {
+    const previous = {
+      filter: {
+        role: 'supplier',
+        search_text: ''
+      }
+    }
+
+    const params = {
+      filter: {
+        search_text: 'ad'
+      }
+    }
+
+    const result = mergeDeep(previous, params)
+
+    expect(result).toEqual({
+      filter: {
+        role: 'supplier',
+        search_text: 'ad'
+      }
+    })
+  })
+
+  it('should deeply merge multiple levels', () => {
+    const a = { a: { b: { c: 1 }, d: 2 } }
+    const b = { a: { b: { c: 3 }, e: 4 } }
+
+    const result = mergeDeep( a, b)
+
+    expect(result).toEqual({
+      a: {
+        b: { c: 3 },
+        d: 2,
+        e: 4
+      }
+    })
+  })
+
+  it('should not mutate the original objects', () => {
+    const a = { foo: { bar: 'baz' } }
+    const b = { foo: { bar: 'qux' } }
+
+    const result = mergeDeep({}, a, b)
+
+    expect(result).toEqual({ foo: { bar: 'qux' } })
+    expect(a.foo.bar).toBe('baz') // confirm a was not mutated
+  })
+})

package/tests/service/laravel/pagination/dataDrivers/RequestDriver.test.ts

@@ -0,0 +1,84 @@
+import { describe, test, expect, vi, beforeEach } from 'vitest'
+import { RequestDriver } from '../../../../../src/service/laravel/pagination'
+import { PaginationDataDto } from '../../../../../src/service/pagination'
+import { PaginationResponse } from '../../../../../src/service/laravel/requests'
+
+// Mocks für Schnittstellen und Klassen
+class MockRequest {
+  setPaginationParams = vi.fn().mockReturnThis()
+  send = vi.fn()
+}
+
+class MockPaginationResponse extends PaginationResponse<any> {
+  protected resolveBody = vi.fn().mockResolvedValue(this.mockBody)
+  private mockBody
+
+  constructor(data: any[]) {
+    super()
+    this.mockBody = data
+  }
+
+  getTotal() {
+    return this.mockBody.length
+  }
+
+  getData() {
+    return this.mockBody
+  }
+}
+
+describe('RequestDriver', () => {
+  let mockRequest: MockRequest
+  let requestDriver: RequestDriver<typeof mockRequest>
+
+  beforeEach(() => {
+    mockRequest = new MockRequest()
+    requestDriver = new RequestDriver(mockRequest as any)
+  })
+
+  test('should call setPaginationParams with correct parameters', async () => {
+    const pageNumber = 1
+    const pageSize = 10
+
+    // Mock PaginationResponse
+    const mockResponse = new MockPaginationResponse([{ id: 1 }, { id: 2 }])
+
+    // Mock send method to resolve to a mock PaginationResponse
+    mockRequest.send.mockResolvedValue(mockResponse)
+    await requestDriver.get(pageNumber, pageSize)
+
+    expect(mockRequest.setPaginationParams).toHaveBeenCalledWith(
+      pageNumber,
+      pageSize
+    )
+  })
+
+  test('should correctly map response to PaginationDataDto', async () => {
+    const pageNumber = 1
+    const pageSize = 10
+
+    const mockData = [{ id: 1 }, { id: 2 }]
+    const mockResponse = new MockPaginationResponse(mockData)
+
+    // Mock send method to resolve to a mock PaginationResponse
+    mockRequest.send.mockResolvedValue(mockResponse)
+
+    const result = await requestDriver.get(pageNumber, pageSize)
+
+    expect(result).toBeInstanceOf(PaginationDataDto)
+    expect(result.data).toEqual(mockData)
+    expect(result.total).toBe(mockData.length)
+  })
+
+  test('should handle request errors gracefully', async () => {
+    const pageNumber = 1
+    const pageSize = 10
+
+    const error = new Error('Request failed')
+    mockRequest.send.mockRejectedValue(error)
+
+    await expect(requestDriver.get(pageNumber, pageSize)).rejects.toThrowError(
+      'Request failed'
+    )
+  })
+})

package/tests/service/laravel/requests/JsonBaseRequest.test.ts

@@ -0,0 +1,43 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import { JsonBaseRequest } from '../../../../src/service/laravel/requests'
+import { JsonResponse } from '../../../../src/service/laravel/requests'
+import { JsonBodyFactory } from '../../../../src/service/requests'
+
+interface TestResource {
+  id: number;
+  name: string;
+}
+
+class TestJsonBaseRequest extends JsonBaseRequest<TestResource> {
+  // Abstrakte Klasse muss hier für Tests konkretisiert werden
+}
+
+describe('JsonBaseRequest', () => {
+  let request: TestJsonBaseRequest;
+
+  beforeEach(() => {
+    // Instanziiere die Testklasse vor jedem Test
+    request = new TestJsonBaseRequest();
+  });
+
+  test('should return a JsonResponse instance from getResponse', () => {
+    const response = request.getResponse();
+    // Überprüfe, ob getResponse eine JsonResponse-Instanz zurückgibt
+    expect(response).toBeInstanceOf(JsonResponse);
+  });
+
+  test('should return a JsonBodyFactory instance from getRequestBodyFactory', () => {
+    const bodyFactory = request.getRequestBodyFactory();
+    // Überprüfe, ob getRequestBodyFactory eine JsonBodyFactory-Instanz zurückgibt
+    expect(bodyFactory).toBeInstanceOf(JsonBodyFactory);
+  });
+
+  test('should handle generic type definitions for JsonResponse and factory', () => {
+    // Testen des generischen Typsystems
+    const response = request.getResponse();
+    const bodyFactory = request.getRequestBodyFactory();
+
+    expect(response).toBeInstanceOf(JsonResponse<TestResource>);
+    expect(bodyFactory).toBeInstanceOf(JsonBodyFactory);
+  });
+});

package/tests/service/laravel/requests/PaginationJsonBaseRequest.test.ts

@@ -0,0 +1,58 @@
+import { describe, test, expect, beforeEach, vi } from 'vitest';
+import { PaginationJsonBaseRequest } from '../../../../src/service/laravel/requests'
+import { PaginationResponse } from '../../../../src/service/laravel/requests'
+
+interface TestResource {
+  id: number;
+  name: string;
+}
+
+interface TestRequestParams {
+  page_number: number;
+  page_size: number;
+}
+
+class TestPaginationJsonBaseRequest extends PaginationJsonBaseRequest<TestResource, TestRequestParams> {
+  // Abstrakte Klasse für Tests konkretisiert
+}
+
+describe('PaginationJsonBaseRequest', () => {
+  let request: TestPaginationJsonBaseRequest;
+
+  beforeEach(() => {
+    // Instanziiere die Testklasse vor jedem Test
+    request = new TestPaginationJsonBaseRequest();
+  });
+
+  test('should return a PaginationResponse instance from getResponse', () => {
+    const response = request.getResponse();
+    // Überprüfe, ob getResponse eine PaginationResponse-Instanz zurückgibt
+    expect(response).toBeInstanceOf(PaginationResponse);
+  });
+
+  test('should correctly set pagination parameters with setPaginationParams', () => {
+    const page = 2;
+    const size = 50;
+
+    // Mock der `withParams`-Methode, falls sie von `BaseRequest` stammt
+    const mockWithParams = vi.spyOn(request, 'withParams');
+
+    // Rufe `setPaginationParams` auf
+    const updatedRequest = request.setPaginationParams(page, size);
+
+    expect(updatedRequest).toBe(request); // Überprüft die fluente API
+    expect(mockWithParams).toHaveBeenCalledWith({
+      page_number: page,
+      page_size: size,
+    });
+
+    // Aufräumen von Mocks
+    mockWithParams.mockRestore();
+  });
+
+  test('should handle generic type definitions for getResponse', () => {
+    // Testen des generischen Typsystems
+    const response = request.getResponse();
+    expect(response).toBeInstanceOf(PaginationResponse<TestResource>);
+  });
+});

package/tests/service/laravel/requests/responses/JsonResponse.test.ts

@@ -0,0 +1,59 @@
+import { describe, test, expect, beforeEach, vi } from 'vitest';
+import { JsonResponse } from '../../../../../src/service/laravel/requests'
+
+describe('JsonResponse', () => {
+  let jsonResponse: JsonResponse<any>; // Generische Instanz für flexibles Testen
+
+  beforeEach(() => {
+    jsonResponse = new JsonResponse();
+  });
+
+  test('should correctly return data from response body', async () => {
+    const mockBody = {
+      data: { id: 1, name: 'Test Resource' },
+    };
+
+    // Simuliere die Methode `setResponse` mit einem Mock-ResponseHandler
+    const mockResponseHandler = {
+      async json() {
+        return mockBody;
+      },
+      getRawResponse: vi.fn(),
+      getStatusCode: vi.fn(),
+      getHeaders: vi.fn(),
+    };
+
+    await jsonResponse.setResponse(mockResponseHandler as any);
+
+    // Rufe die Methode `getData` auf und erwarte die korrekten Daten
+    const data = jsonResponse.getData();
+    expect(data).toEqual(mockBody.data);
+  });
+
+  test('should throw error if body is not set before calling getData', () => {
+    // Direkt getData aufrufen ohne vorher einen Response-Body zu setzen
+    expect(() => jsonResponse.getData()).toThrowError('Response body is not set');
+  });
+
+  test('should correctly handle nested resource data', async () => {
+    const mockBody = {
+      data: { id: 42, attributes: { title: 'Nested Test' } },
+    };
+
+    // Simuliere die Methode `setResponse` mit einem Mock-ResponseHandler
+    const mockResponseHandler = {
+      async json() {
+        return mockBody;
+      },
+      getRawResponse: vi.fn(),
+      getStatusCode: vi.fn(),
+      getHeaders: vi.fn(),
+    };
+
+    await jsonResponse.setResponse(mockResponseHandler as any);
+
+    // Rufe die Methode `getData` auf und überprüfe, ob die geschachtelten Daten korrekt verarbeitet werden
+    const data = jsonResponse.getData();
+    expect(data).toEqual(mockBody.data);
+  });
+});