@katlux/providers 0.1.0-beta.0

package/services/RequestProvider/RequestProvider.ts

@@ -0,0 +1,165 @@
+import { ECacheStrategy, type IRequestOptions } from '../types'
+import { CacheProviderFactory } from '../CacheProvider/CacheProviderFactory'
+import { ACacheProvider } from '../CacheProvider/ACacheProvider'
+
+interface IQueuedRequest {
+	url: string
+	options?: IRequestOptions
+	instance: RequestProvider
+	nuxtApp?: any
+	resolve?: (value: unknown) => void
+	reject?: (error: Error) => void
+}
+
+export class RequestProvider {
+	cacheProvider: ACacheProvider | null = null
+	cacheLifetime: number | null = 60 * 60 * 1000
+	deduplicate: boolean = true
+	cacheKey: string = ""
+	private static requestQueue: IQueuedRequest[] = []
+	private static executing: boolean = false
+	private static requestsInFlight: Map<string, Promise<any>> = new Map()
+
+	constructor(provider?: ACacheProvider | ECacheStrategy, lifetime?: number, deduplicate?: boolean) {
+		if (provider) this.setCacheProvider(provider)
+		if (lifetime) this.setCacheLifetime(lifetime)
+		if (deduplicate !== undefined) this.setDeduplicate(deduplicate)
+	}
+
+	setCacheProvider(provider?: ACacheProvider | ECacheStrategy): void {
+		if (!provider) {
+			console.warn("RequestProvider: provider is required")
+		}
+
+		if (provider instanceof ACacheProvider) this.cacheProvider = provider
+		else this.cacheProvider = CacheProviderFactory.getProvider(provider as ECacheStrategy)
+	}
+
+	setCacheLifetime(lifetime: number): void {
+		this.cacheLifetime = lifetime
+	}
+
+	setDeduplicate(deduplicate: boolean): void {
+		this.deduplicate = deduplicate
+	}
+
+	private getUniqueKey(url: string, options?: IRequestOptions): string {
+		if (options?.key) return options.key
+		const { query, body, headers, method } = options || {}
+
+		// Stable stringification: treats undefined as null for consistency
+		const stableStringify = (val: any) => JSON.stringify(val === undefined ? null : val)
+
+		return [
+			url,
+			stableStringify(query || {}),
+			stableStringify(body || null),
+			stableStringify(headers || {}),
+			method || 'GET'
+		].join('|')
+	}
+
+	registerRequest<T>(url: string, options?: IRequestOptions): Promise<T> {
+		const uniqueKey = this.getUniqueKey(url, options)
+		const shouldDeduplicate = options?.deduplicate ?? this.deduplicate
+
+		if (shouldDeduplicate && RequestProvider.requestsInFlight.has(uniqueKey)) {
+			return RequestProvider.requestsInFlight.get(uniqueKey) as Promise<T>
+		}
+
+		// Context is optional here, we'll try to get it during execution if needed
+		const promise = new Promise<T>((resolve, reject) => {
+			RequestProvider.requestQueue.push({
+				url,
+				options,
+				instance: this,
+				resolve: resolve as (value: unknown) => void,
+				reject: reject as (error: Error) => void
+			})
+			RequestProvider.executeAll()
+		}).finally(() => {
+			if (shouldDeduplicate) {
+				RequestProvider.requestsInFlight.delete(uniqueKey)
+			}
+		})
+
+		if (shouldDeduplicate) {
+			RequestProvider.requestsInFlight.set(uniqueKey, promise)
+		}
+
+		return promise
+	}
+
+	static executeAll(): void {
+		if (RequestProvider.executing) return
+		if (RequestProvider.requestQueue.length === 0) return
+
+		RequestProvider.executing = true
+		const queue = [...RequestProvider.requestQueue]
+		RequestProvider.requestQueue = []
+
+		queue.forEach((queuedRequest) => {
+			queuedRequest.instance.request(queuedRequest.url, queuedRequest.options)
+				.then((result) => queuedRequest.resolve?.(result))
+				.catch((error) => queuedRequest.reject?.(error instanceof Error ? error : new Error(String(error))))
+		})
+
+		Promise.resolve().then(() => {
+			RequestProvider.executing = false
+			if (RequestProvider.requestQueue.length > 0) {
+				RequestProvider.executeAll()
+			}
+		})
+	}
+
+	async request<T>(url: string, options?: IRequestOptions): Promise<T> {
+		const { cacheStrategy, lifetime, query, body, headers, method } = options || {}
+		const uniqueKey = this.getUniqueKey(url, options)
+
+		// Get context if possible (environment agnostic)
+		const nuxtApp = options?.nuxtApp
+		let serverHeaders = {}
+
+		if (nuxtApp && import.meta.server) {
+			const req = (nuxtApp as any).node?.req || (nuxtApp as any).ssrContext?.event?.node?.req
+			if (req?.headers?.cookie) {
+				serverHeaders = { cookie: req.headers.cookie }
+			}
+		}
+
+		const provider = cacheStrategy ? CacheProviderFactory.getProvider(cacheStrategy) : this.cacheProvider
+		const cacheLifetime = lifetime || this.cacheLifetime
+
+		// Use 'GET' as default if method is undefined
+		const requestMethod = method || 'GET'
+		const isGetRequest = requestMethod === 'GET'
+
+		// 1. Check Cache (Only for GET requests and if NOT disabled)
+		if (provider && isGetRequest && !options?.disableCache) {
+			const cached = await provider.get<T>(uniqueKey, nuxtApp)
+			if (cached) {
+				console.log(`[RequestProvider] CACHE HIT: ${url}`)
+				return cached
+			}
+			console.log(`[RequestProvider] CACHE MISS: ${url}`)
+		}
+
+
+		// 2. Perform Request
+		const fetchOptions: any = {
+			method: requestMethod,
+			body: body,
+			headers: { ...headers, ...serverHeaders },
+			query: query
+		}
+
+		// $fetch is universal in Nuxt 3
+		const responseData = await ($fetch as any)(url, fetchOptions) as T
+
+		// 3. Save to Cache (Only for GET requests)
+		if (provider && cacheLifetime && responseData && isGetRequest) {
+			await provider.set(uniqueKey, responseData, cacheLifetime, nuxtApp)
+		}
+		return responseData
+	}
+}

package/services/RequestProvider/serverCache.ts

@@ -0,0 +1,24 @@
+import type { ICacheEntry } from './types'
+
+// Global cache storage for Application strategy (Server Side Only)
+const applicationCache = new Map<string, ICacheEntry<any>>()
+
+export const getServerCache = <T>(key: string): T | null => {
+	const entry = applicationCache.get(key)
+	if (!entry) return null
+
+	if (Date.now() - entry.timestamp > entry.lifetime) {
+		applicationCache.delete(key)
+		return null
+	}
+
+	return entry.data as T
+}
+
+export const setServerCache = <T>(key: string, data: T, lifetime: number) => {
+	applicationCache.set(key, {
+		data,
+		timestamp: Date.now(),
+		lifetime
+	})
+}

package/services/index.ts

@@ -0,0 +1,19 @@
+export * from './types'
+export * from './DataProvider/CFlatClientDataProvider'
+export * from './DataProvider/CAPIFlatClientDataProvider'
+export * from './DataProvider/CAPIFlatServerDataProvider'
+export * from './DataProvider/ADataProvider'
+export * from './DataProvider/AAPIDataProvider'
+export * from './DataProvider/CFlatServerDataProvider'
+export * from './DataProvider/CTreeClientDataProvider'
+export * from './DataProvider/CAPITreeClientDataProvider'
+export * from './DataProvider/CTreeServerDataProvider'
+export * from './DataProvider/CAPITreeServerDataProvider'
+export * from './CacheProvider/CacheProviderFactory'
+export * from './CacheProvider/CSessionCache'
+export * from './CacheProvider/CCookieCache'
+export * from './CacheProvider/CLocalStorageCache'
+export * from './CacheProvider/CIndexedDBCache'
+export * from './CacheProvider/CMemoryCache'
+export * from './CacheProvider/CApplicationCache'
+export * from './RequestProvider/RequestProvider'

package/services/types.ts

@@ -0,0 +1,172 @@
+import type { Ref } from 'vue'
+
+// ============================================================================
+// Cache-related Types
+// ============================================================================
+
+export enum ECacheStrategy {
+	Application = 'Application',
+	Session = 'Session',
+	Memory = 'Memory',
+	LocalStorage = 'LocalStorage',
+	IndexedDB = 'IndexedDB',
+	Cookie = 'Cookie'
+}
+
+export interface ICacheEntry<T> {
+	data: T
+	timestamp: number
+	lifetime: number
+}
+
+// ============================================================================
+// Request Provider Types
+// ============================================================================
+
+export interface IRequestOptions {
+	method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+	body?: any
+	headers?: Record<string, string>
+	cacheStrategy?: ECacheStrategy
+	lifetime?: number // milliseconds
+	key?: string // Unique key for caching, required if cacheStrategy is used
+	cacheKey?: string // context/namespace key for shared cache storage
+	query?: Record<string, any>
+	deduplicate?: boolean
+	nuxtApp?: any
+	disableCache?: boolean
+}
+
+// ============================================================================
+// Data Provider Types
+// ============================================================================
+
+export interface IKDatatableAction {
+	action: Function
+	label: string
+}
+
+// DataRow is a map for a data row
+export type TDataRow = { [key: string]: any }
+
+export enum EDataFilterOperator {
+	Equal = "==",
+	NotEqual = "!=",
+	GreaterThan = ">",
+	LessThan = "<",
+	GreaterThanOrEqual = ">=",
+	LessThanOrEqual = "<=",
+	In = "in",
+	NotIn = "nin",
+	And = "and",
+	Or = "or",
+	Nand = "nand",
+	Nor = "nor"
+}
+
+// DataFilter interface for filtering data
+export interface IDataFilter {
+	operator: EDataFilterOperator
+	field: TDataRow | IDataFilter[]
+	active: Boolean
+}
+
+// DataSort interface for sorting data
+export interface IDataSort {
+	field: string
+	direction: 'asc' | 'desc'
+}
+
+// DataResult interface for the result
+export interface IDataResult {
+	rowCount: number
+	rows: TDataRow[]
+}
+
+// Function type for getting a page of data
+export type TPageDataHandler = (currentPage: number, pageSize: number, filter: IDataFilter, sortList: IDataSort[], options?: { disableCache?: boolean }) => IDataResult | Promise<IDataResult>;
+
+export interface IDataProviderOptions {
+	filter?: IDataFilter
+	sortList?: IDataSort[]
+	pageSize?: number
+	currentPage?: number
+	SSR?: boolean
+	cacheStrategy?: ECacheStrategy
+	cacheLifetime?: number
+	deduplicate?: boolean
+	nuxtApp?: any
+	urlPageParam?: string  // URL query param key for page sync (e.g., 'page', 'p')
+	refreshOnMutation?: boolean
+}
+
+// ============================================================================
+// Tree Data Provider Types
+// ============================================================================
+
+export interface ITreeNode {
+	data: TDataRow
+	id: string | number
+	parentId: string | number | null
+	depth: number
+	hasChildren: boolean
+	isExpanded: boolean
+}
+
+// Internal node without expansion state (static structure)
+export interface ITreeNodeStatic {
+	data: TDataRow
+	id: string | number
+	parentId: string | number | null
+	depth: number
+	hasChildren: boolean
+}
+
+export type TreePaginationMode = 'all' | 'root'
+
+export interface ITreeDataProviderOptions extends IDataProviderOptions {
+	parentKey?: string
+	idKey?: string
+	expandedByDefault?: boolean
+	paginateBy?: TreePaginationMode
+}
+
+/**
+ * Tree-specific page data handler that includes tree parameters
+ * Server handles tree building, visibility, and pagination
+ */
+export type TTreePageDataHandler = (
+	currentPage: number,
+	pageSize: number,
+	filter: IDataFilter,
+	sortList: IDataSort[],
+	treeParams: {
+		expandedNodes: (string | number)[],
+		parentKey: string,
+		idKey: string,
+		paginateBy: TreePaginationMode,
+		expandedByDefault: boolean
+	},
+	options?: { disableCache?: boolean }
+) => IDataResult | Promise<IDataResult>;
+
+// ============================================================================
+// Product Types
+// ============================================================================
+
+export interface KProductItemData {
+	id: string | number
+	title: string
+	image?: string
+	price?: number
+	currency?: string
+	description?: string
+	[key: string]: any
+}
+
+export interface KProductRowAction {
+	label: string
+	icon?: string
+	action: (item: KProductItemData) => void
+	color?: 'primary' | 'danger' | 'success' | 'warning' | 'info' | 'light' | 'dark' | 'default'
+}

package/src/index.ts

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