@goplusvn/core 0.1.0 → 0.1.2

package/src/infrastructure/__tests__/architecture-verification.spec.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi } from "vitest";
+import { LockManager } from "../lock/lock-manager";
+import { WithLock } from "../lock/decorators";
+import type { CacheOptions, Cache } from "../cache/types";
+import { CacheNamespace } from "../cache/types";
+
+// Mock Cache Implementation for Testing
+class MockCache implements Cache {
+  private store = new Map<string, any>();
+  async get<T>(key: string): Promise<T | undefined> {
+    return this.store.get(key);
+  }
+  async set<T>(key: string, value: T): Promise<void> {
+    this.store.set(key, value);
+  }
+  async del(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+  async has(key: string): Promise<boolean> {
+    return this.store.has(key);
+  }
+  async reset(): Promise<void> {
+    this.store.clear();
+  }
+  async keys(): Promise<string[]> {
+    return Array.from(this.store.keys());
+  }
+}
+
+describe("Architecture Verification: Phase 2 Enhancements", () => {
+  describe("2.2 Concurrency Control (LockManager)", () => {
+    it("should acquire and release lock successfully", async () => {
+      const cache = new MockCache();
+      const lockManager = new LockManager(cache);
+      const resourceId = "order-123";
+
+      const acquired = await lockManager.acquire(resourceId, { ttl: 1000 });
+      expect(acquired).toBe(true);
+
+      const isLocked = await cache.has(resourceId);
+      expect(isLocked).toBe(true);
+
+      await lockManager.release(resourceId);
+      const isLockedAfterRelease = await cache.has(resourceId);
+      expect(isLockedAfterRelease).toBe(false);
+    });
+
+    it("should fail to acquire lock if already locked", async () => {
+      const cache = new MockCache();
+      const lockManager = new LockManager(cache);
+      const resourceId = "order-456";
+
+      await lockManager.acquire(resourceId, { ttl: 5000 }); // Lock 1
+      const acquiredAgain = await lockManager.acquire(resourceId, {
+        ttl: 1000,
+      }); // Lock 2
+
+      expect(acquiredAgain).toBe(false);
+    });
+  });
+
+  describe("2.2 Decorator Usage (@WithLock)", () => {
+    it("should execute method with lock", async () => {
+      const cache = new MockCache();
+      const lockManager = new LockManager(cache);
+
+      class OrderService {
+        lockManager = lockManager;
+        executionCount = 0;
+
+        @WithLock("{0}")
+        async processOrder(orderId: string) {
+          this.executionCount++;
+          return `Processed ${orderId}`;
+        }
+      }
+
+      const service = new OrderService();
+      const result = await service.processOrder("100");
+
+      expect(result).toBe("Processed 100");
+      expect(service.executionCount).toBe(1);
+      // Lock should be released after execution
+      expect(await cache.has("lock:order-100")).toBe(false);
+    });
+  });
+
+  describe("2.3 Namespace Caching Strategy", () => {
+    it("should define CacheNamespace enum correctly", () => {
+      expect(CacheNamespace.Auth).toBe("auth");
+      expect(CacheNamespace.TenantConfig).toBe("tenant-config");
+    });
+
+    it("should allow configuring cache with namespace (Simulation)", () => {
+      // This tests the TYPE definition and intent, as actual implementation depends on the Factory we haven't fully refactored yet.
+      const options: CacheOptions = {
+        name: "redis",
+        prefix: CacheNamespace.Auth,
+      };
+      expect(options.prefix).toBe("auth");
+    });
+  });
+});

package/src/infrastructure/api-service.ts

@@ -0,0 +1,317 @@
+/**
+ * @goerp/core - Abstract API Service Layer
+ * Inspired by Plane's APIService pattern (packages/services/src/api.service.ts)
+ *
+ * Provides a centralized HTTP client base class for all domain services.
+ * Features:
+ * - Centralized error handling & 401 redirect
+ * - Request/Response interceptors
+ * - Type-safe CRUD methods
+ * - Automatic retry logic (configurable)
+ *
+ * @example
+ * ```typescript
+ * class CustomerService extends APIService {
+ *   constructor() { super('/api/sales/customers') }
+ *
+ *   async list(filters?: CustomerFilters) {
+ *     return this.get<PaginatedResponse<Customer>>('/', { params: filters })
+ *   }
+ *
+ *   async getById(id: string) {
+ *     return this.get<Customer>(`/${id}`)
+ *   }
+ *
+ *   async create(data: CreateCustomerDTO) {
+ *     return this.post<Customer>('/', data)
+ *   }
+ * }
+ * ```
+ */
+
+// ============================================================
+// Types
+// ============================================================
+
+export interface APIRequestConfig {
+  params?: Record<string, unknown>
+  headers?: Record<string, string>
+  signal?: AbortSignal
+  /** Override default timeout (ms) */
+  timeout?: number
+}
+
+export interface APIResponse<T = unknown> {
+  data: T
+  status: number
+  ok: boolean
+}
+
+export interface APIError {
+  message: string
+  status: number
+  code?: string
+  details?: unknown
+}
+
+export interface APIServiceOptions {
+  /** Called when a 401 response is received */
+  onUnauthorized?: () => void
+  /** Called before each request (e.g., for logging) */
+  onRequest?: (method: string, url: string) => void
+  /** Called after each response (e.g., for logging) */
+  onResponse?: (method: string, url: string, status: number) => void
+  /** Called on any error */
+  onError?: (error: APIError) => void
+  /** Default timeout in ms (default: 30000) */
+  timeout?: number
+  /** Default headers to include in every request */
+  defaultHeaders?: Record<string, string>
+}
+
+// ============================================================
+// APIService Base Class
+// ============================================================
+
+/**
+ * Abstract base class for making HTTP requests using fetch API.
+ * All domain services (CustomerService, OrderService, etc.) should extend this class.
+ *
+ * Unlike Plane's axios-based approach, we use native fetch() for Next.js compatibility
+ * (better SSR support, no extra dependency, works with Server Components).
+ */
+export abstract class APIService {
+  protected readonly baseURL: string
+  private readonly options: APIServiceOptions
+
+  constructor(baseURL: string, options: APIServiceOptions = {}) {
+    this.baseURL = baseURL
+    this.options = options
+  }
+
+  // --------------------------------------------------------
+  // Core HTTP Methods
+  // --------------------------------------------------------
+
+  /**
+   * Makes a GET request to the specified endpoint
+   */
+  protected async get<T = unknown>(
+    endpoint: string = "",
+    config: APIRequestConfig = {}
+  ): Promise<T> {
+    const url = this.buildURL(endpoint, config.params)
+    return this.request<T>("GET", url, undefined, config)
+  }
+
+  /**
+   * Makes a POST request with JSON body
+   */
+  protected async post<T = unknown>(
+    endpoint: string = "",
+    data?: unknown,
+    config: APIRequestConfig = {}
+  ): Promise<T> {
+    const url = this.buildURL(endpoint)
+    return this.request<T>("POST", url, data, config)
+  }
+
+  /**
+   * Makes a PUT request with JSON body
+   */
+  protected async put<T = unknown>(
+    endpoint: string = "",
+    data?: unknown,
+    config: APIRequestConfig = {}
+  ): Promise<T> {
+    const url = this.buildURL(endpoint)
+    return this.request<T>("PUT", url, data, config)
+  }
+
+  /**
+   * Makes a PATCH request with JSON body
+   */
+  protected async patch<T = unknown>(
+    endpoint: string = "",
+    data?: unknown,
+    config: APIRequestConfig = {}
+  ): Promise<T> {
+    const url = this.buildURL(endpoint)
+    return this.request<T>("PATCH", url, data, config)
+  }
+
+  /**
+   * Makes a DELETE request
+   */
+  protected async delete<T = unknown>(
+    endpoint: string = "",
+    data?: unknown,
+    config: APIRequestConfig = {}
+  ): Promise<T> {
+    const url = this.buildURL(endpoint)
+    return this.request<T>("DELETE", url, data, config)
+  }
+
+  // --------------------------------------------------------
+  // Internal Helpers
+  // --------------------------------------------------------
+
+  /**
+   * Build full URL with query params
+   */
+  private buildURL(endpoint: string, params?: Record<string, unknown>): string {
+    const url = `${this.baseURL}${endpoint}`
+    if (!params || Object.keys(params).length === 0) return url
+
+    const searchParams = new URLSearchParams()
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined && value !== null && value !== "") {
+        searchParams.append(key, String(value))
+      }
+    }
+
+    const queryString = searchParams.toString()
+    return queryString ? `${url}?${queryString}` : url
+  }
+
+  /**
+   * Core request method — all HTTP methods funnel through here.
+   * Handles: headers, body, timeout, error handling, 401 redirect.
+   */
+  private async request<T>(
+    method: string,
+    url: string,
+    data?: unknown,
+    config: APIRequestConfig = {}
+  ): Promise<T> {
+    // Notify interceptor
+    this.options.onRequest?.(method, url)
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      ...this.options.defaultHeaders,
+      ...config.headers,
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers,
+      credentials: "include", // Send cookies (same as axios withCredentials)
+      signal: config.signal,
+    }
+
+    // Attach body for non-GET methods
+    if (data !== undefined && method !== "GET") {
+      fetchOptions.body = JSON.stringify(data)
+    }
+
+    try {
+      const response = await fetch(url, fetchOptions)
+
+      // Notify response interceptor
+      this.options.onResponse?.(method, url, response.status)
+
+      // Handle 401 — Centralized unauthorized redirect
+      if (response.status === 401) {
+        const error: APIError = {
+          message: "Unauthorized",
+          status: 401,
+          code: "UNAUTHORIZED",
+        }
+        this.options.onUnauthorized?.()
+        this.options.onError?.(error)
+        throw error
+      }
+
+      // Handle other error statuses
+      if (!response.ok) {
+        let errorBody: unknown
+        try {
+          errorBody = await response.json()
+        } catch {
+          errorBody = await response.text()
+        }
+
+        const error: APIError = {
+          message:
+            typeof errorBody === "object" && errorBody !== null && "message" in errorBody
+              ? String((errorBody as Record<string, unknown>).message)
+              : `HTTP Error ${response.status}`,
+          status: response.status,
+          code:
+            typeof errorBody === "object" && errorBody !== null && "code" in errorBody
+              ? String((errorBody as Record<string, unknown>).code)
+              : undefined,
+          details: errorBody,
+        }
+        this.options.onError?.(error)
+        throw error
+      }
+
+      // Handle empty responses (204 No Content)
+      if (response.status === 204) {
+        return undefined as T
+      }
+
+      // Parse JSON response
+      const responseData = await response.json()
+      return responseData as T
+    } catch (error) {
+      // Re-throw APIError as-is
+      if (this.isAPIError(error)) {
+        throw error
+      }
+
+      // Wrap network/timeout errors
+      const apiError: APIError = {
+        message: error instanceof Error ? error.message : "Network error",
+        status: 0,
+        code: "NETWORK_ERROR",
+      }
+      this.options.onError?.(apiError)
+      throw apiError
+    }
+  }
+
+  /**
+   * Type guard for APIError
+   */
+  private isAPIError(error: unknown): error is APIError {
+    return (
+      typeof error === "object" &&
+      error !== null &&
+      "message" in error &&
+      "status" in error
+    )
+  }
+}
+
+// ============================================================
+// Pre-configured Service Factory
+// ============================================================
+
+/**
+ * Default options for client-side services.
+ * Handles 401 redirect to login page automatically.
+ */
+export const defaultClientOptions: APIServiceOptions = {
+  onUnauthorized: () => {
+    if (typeof window !== "undefined") {
+      const currentPath = window.location.pathname
+      window.location.replace(`/login?next_path=${encodeURIComponent(currentPath)}`)
+    }
+  },
+}
+
+/**
+ * Helper to check if an error is an APIError
+ */
+export function isAPIError(error: unknown): error is APIError {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "message" in error &&
+    "status" in error &&
+    typeof (error as APIError).status === "number"
+  )
+}

package/src/infrastructure/cache/cache-manager.ts

@@ -0,0 +1,107 @@
+import type {
+  Cache,
+  CacheManager as ICacheManager,
+  CacheManagerOptions,
+  CacheOptions,
+} from "./types";
+import { MemoryCache } from "./cache";
+
+/**
+ * CacheManager - manages multiple cache instances
+ *
+ * @example
+ * ```typescript
+ * import { cacheManager } from '@goerp/core/infrastructure';
+ *
+ * const userCache = cacheManager.create({ name: 'users', ttl: 3600 });
+ * await userCache.set('user:123', userData);
+ * const user = await userCache.get('user:123');
+ * ```
+ */
+class CacheManagerImpl implements ICacheManager {
+  private caches = new Map<string, Cache>();
+  private options: CacheManagerOptions;
+
+  constructor(options: CacheManagerOptions = {}) {
+    this.options = {
+      defaultTtl: options.defaultTtl || 3600,
+      prefix: options.prefix || "",
+    };
+  }
+
+  create(options: CacheOptions): Cache {
+    const existing = this.caches.get(options.name);
+    if (existing) {
+      return existing;
+    }
+
+    const cache = new MemoryCache({
+      ...options,
+      ttl: options.ttl || this.options.defaultTtl,
+      prefix: this.options.prefix,
+    });
+
+    this.caches.set(options.name, cache);
+    return cache;
+  }
+
+  get(name: string): Cache | undefined {
+    return this.caches.get(name);
+  }
+
+  async flushAll(): Promise<void> {
+    const promises: Promise<void>[] = [];
+    for (const cache of this.caches.values()) {
+      promises.push(cache.reset());
+    }
+    await Promise.all(promises);
+  }
+
+  /** Get all cache names */
+  getAllCaches(): string[] {
+    return Array.from(this.caches.keys());
+  }
+
+  /** Get stats for all caches (for admin dashboard) */
+  async getStats(): Promise<
+    Array<{ name: string; itemCount: number; ttl: number }>
+  > {
+    const stats: Array<{ name: string; itemCount: number; ttl: number }> = [];
+
+    for (const [name, cache] of this.caches.entries()) {
+      const keys = await cache.keys();
+      stats.push({
+        name,
+        itemCount: keys.length,
+        ttl: (cache as MemoryCache).getInfo().ttl,
+      });
+    }
+
+    return stats;
+  }
+
+  /** Clear a specific cache by name */
+  async clearCache(name: string): Promise<boolean> {
+    const cache = this.caches.get(name);
+    if (cache) {
+      await cache.reset();
+      return true;
+    }
+    return false;
+  }
+}
+
+// Singleton instance pattern stable across hot-reloads
+const globalForCache = globalThis as unknown as {
+  coreCacheManager: CacheManagerImpl | undefined;
+};
+
+export const cacheManager =
+  globalForCache.coreCacheManager ?? new CacheManagerImpl();
+
+if (process.env.NODE_ENV !== "production") {
+  globalForCache.coreCacheManager = cacheManager;
+}
+
+// Export class for testing
+export { CacheManagerImpl };

package/src/infrastructure/cache/cache.ts

@@ -0,0 +1,120 @@
+import type { Cache, CacheOptions } from "./types";
+
+interface CacheEntry<T> {
+  value: T;
+  expireAt: number | null;
+}
+
+/**
+ * Simple in-memory cache implementation
+ */
+export class MemoryCache implements Cache {
+  private store = new Map<string, CacheEntry<unknown>>();
+  private name: string;
+  private defaultTtl: number;
+  private maxSize: number;
+  private prefix: string;
+
+  constructor(options: CacheOptions & { prefix?: string }) {
+    this.name = options.name;
+    this.defaultTtl = options.ttl || 3600;
+    this.maxSize = options.max || 1000;
+    this.prefix = options.prefix || "";
+  }
+
+  private getFullKey(key: string): string {
+    return this.prefix
+      ? `${this.prefix}:${this.name}:${key}`
+      : `${this.name}:${key}`;
+  }
+
+  private isExpired(entry: CacheEntry<unknown>): boolean {
+    if (entry.expireAt === null) return false;
+    return Date.now() > entry.expireAt;
+  }
+
+  private cleanup(): void {
+    for (const [key, entry] of this.store.entries()) {
+      if (this.isExpired(entry)) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  async get<T>(key: string): Promise<T | undefined> {
+    const fullKey = this.getFullKey(key);
+    const entry = this.store.get(fullKey);
+
+    if (!entry) return undefined;
+
+    if (this.isExpired(entry)) {
+      this.store.delete(fullKey);
+      return undefined;
+    }
+
+    return entry.value as T;
+  }
+
+  async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+    const fullKey = this.getFullKey(key);
+    const ttlSeconds = ttl ?? this.defaultTtl;
+
+    // Enforce max size
+    if (this.store.size >= this.maxSize) {
+      this.cleanup();
+      // If still full, remove oldest
+      if (this.store.size >= this.maxSize) {
+        const firstKey = this.store.keys().next().value;
+        if (firstKey) this.store.delete(firstKey);
+      }
+    }
+
+    this.store.set(fullKey, {
+      value,
+      expireAt: ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : null,
+    });
+  }
+
+  async del(key: string): Promise<void> {
+    const fullKey = this.getFullKey(key);
+    this.store.delete(fullKey);
+  }
+
+  async has(key: string): Promise<boolean> {
+    const value = await this.get(key);
+    return value !== undefined;
+  }
+
+  async reset(): Promise<void> {
+    // Only clear keys for this cache (by prefix)
+    const prefix = this.getFullKey("");
+    for (const key of this.store.keys()) {
+      if (key.startsWith(prefix)) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  async keys(): Promise<string[]> {
+    this.cleanup();
+    const prefix = this.getFullKey("");
+    const result: string[] = [];
+
+    for (const key of this.store.keys()) {
+      if (key.startsWith(prefix)) {
+        result.push(key.slice(prefix.length));
+      }
+    }
+
+    return result;
+  }
+
+  /** Get cache info for admin dashboard */
+  getInfo(): { name: string; ttl: number; maxSize: number } {
+    return {
+      name: this.name,
+      ttl: this.defaultTtl,
+      maxSize: this.maxSize,
+    };
+  }
+}

package/src/infrastructure/cache/index.ts

@@ -0,0 +1,8 @@
+export { cacheManager, CacheManagerImpl } from "./cache-manager";
+export { MemoryCache } from "./cache";
+export type {
+  Cache,
+  CacheOptions,
+  CacheManager,
+  CacheManagerOptions,
+} from "./types";

package/src/infrastructure/cache/types.ts

@@ -0,0 +1,48 @@
+export enum CacheNamespace {
+  Auth = "auth",
+  Lock = "lock",
+  Metadata = "metadata",
+  TenantConfig = "tenant-config",
+  RateLimit = "rate-limit",
+}
+
+export interface CacheOptions {
+  /**
+   * Name of the cache store (e.g. 'redis', 'memory')
+   */
+  name: string;
+  /**
+   * Default TTL in seconds
+   */
+  ttl?: number;
+  /**
+   * Max number of items (for memory cache)
+   */
+  max?: number;
+  /**
+   * Namespace prefix for all keys in this cache instance
+   */
+  prefix?: CacheNamespace | string;
+}
+
+export interface Cache {
+  get<T>(key: string): Promise<T | undefined>;
+  set<T>(key: string, value: T, ttl?: number): Promise<void>;
+  del(key: string): Promise<void>;
+  has(key: string): Promise<boolean>;
+  reset(): Promise<void>;
+  keys(): Promise<string[]>;
+}
+export interface CacheManagerOptions {
+  defaultTtl?: number;
+  prefix?: string;
+}
+
+export interface CacheManager {
+  create(options: CacheOptions): Cache;
+  get(name: string): Cache | undefined;
+  flushAll(): Promise<void>;
+  getAllCaches(): string[];
+  getStats(): Promise<Array<{ name: string; itemCount: number; ttl: number }>>;
+  clearCache(name: string): Promise<boolean>;
+}