@katlux/providers 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present, The Katlux Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @katlux/providers
+
+Core providers and services for the Katlux UI framework.
+
+## Installation
+
+```bash
+npm install @katlux/providers
+```
+
+## Trademark Policy
+
+The code in this repository is completely free and open-source under the MIT License. 
+However, **Katlux™** and the Katlux logo are unregistered trademarks of the Katlux project. 
+
+To protect our users from fraud, you may not use the "Katlux" name or logo to brand your own modified forks, derivative works, or malicious distributions without explicit permission. You are, however, completely free to state "Built with Katlux" in your projects!

package/build.config.ts

@@ -0,0 +1,4 @@
+export default {
+	failOnWarn: false,
+	externals: ['#app', '@katlux/toolkit']
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+	"name": "@katlux/providers",
+	"version": "0.1.0-beta.0",
+	"description": "Core data calculation and caching providers for the Katlux ecosystem",
+	"author": "Katlux",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"main": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "unbuild",
+		"dev": "unbuild --stub"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.mjs",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"dependencies": {}
+}

package/services/CacheProvider/ACacheProvider.ts

@@ -0,0 +1,13 @@
+export abstract class ACacheProvider {
+	constructor() {
+		// Cleanup expired entries on initialization
+		this.cleanupExpired()
+	}
+	abstract getKeyList(nuxtApp?: any): Array<string> | Promise<Array<string>>
+	abstract get<T>(key: string, nuxtApp?: any): Promise<T | null>
+	abstract set<T>(key: string, data: T, lifetime: number, nuxtApp?: any): Promise<void>
+	abstract remove(key: string, nuxtApp?: any): Promise<void>
+	abstract removeByPrefix(prefix: string, nuxtApp?: any): Promise<void>
+	abstract getRemainingTime(key: string, nuxtApp?: any): Promise<number | null>
+	abstract cleanupExpired(): Promise<void>
+}

package/services/CacheProvider/CApplicationCache.ts

@@ -0,0 +1,123 @@
+import { ACacheProvider } from './ACacheProvider'
+import type { ICacheEntry } from '../types'
+
+export class CApplicationCache extends ACacheProvider {
+	private static instance: CApplicationCache | null = null
+	private static _storage: Map<string, ICacheEntry<any>> | null = null
+
+	private static get storage(): Map<string, ICacheEntry<any>> {
+		if (!this._storage) {
+			this._storage = new Map<string, ICacheEntry<any>>()
+		}
+		return this._storage
+	}
+
+	public static getInstance(): CApplicationCache {
+		if (!this.instance) {
+			this.instance = new CApplicationCache()
+		}
+		return this.instance
+	}
+
+	public static getSnapshot(): Map<string, ICacheEntry<any>> {
+		return this.storage
+	}
+
+	private constructor() {
+		super()
+	}
+
+	async getKeyList(nuxtApp?: any): Promise<Array<string>> {
+		const prefix = 'cache:'
+		const storage = CApplicationCache.storage
+		return Array.from(storage.keys())
+			.filter(key => key.startsWith(prefix))
+			.map(key => key.substring(prefix.length))
+	}
+
+	async get<T>(key: string, nuxtApp?: any): Promise<T | null> {
+		if (import.meta.server) {
+			const prefixedKey = 'cache:' + key
+			const storage = CApplicationCache.storage
+			const entry = storage.get(prefixedKey)
+			if (!entry) return null
+
+			if (Date.now() - entry.timestamp > entry.lifetime) {
+				storage.delete(prefixedKey)
+				return null
+			}
+
+			return entry.data as T
+		}
+		return null
+	}
+
+	async set<T>(key: string, data: T, lifetime: number, nuxtApp?: any): Promise<void> {
+		if (import.meta.server) {
+			const prefixedKey = 'cache:' + key
+			const storage = CApplicationCache.storage
+			storage.set(prefixedKey, {
+				data,
+				timestamp: Date.now(),
+				lifetime
+			})
+		}
+	}
+
+	async remove(key: string, nuxtApp?: any): Promise<void> {
+		if (import.meta.server) {
+			const prefixedKey = 'cache:' + key
+			CApplicationCache.storage.delete(prefixedKey)
+		}
+	}
+
+	async removeByPrefix(prefix: string, nuxtApp?: any): Promise<void> {
+		if (import.meta.server) {
+			const fullPrefix = 'cache:' + prefix
+			const storage = CApplicationCache.storage
+			const keysToDelete: string[] = []
+
+			for (const key of storage.keys()) {
+				if (key.startsWith(fullPrefix)) {
+					keysToDelete.push(key)
+				}
+			}
+
+			for (const key of keysToDelete) {
+				storage.delete(key)
+			}
+		}
+	}
+
+	async getRemainingTime(key: string, nuxtApp?: any): Promise<number | null> {
+		if (import.meta.server) {
+			const prefixedKey = 'cache:' + key
+			const storage = CApplicationCache.storage
+			const entry = storage.get(prefixedKey)
+			if (!entry) return null
+			return Math.max(0, (entry.timestamp + entry.lifetime) - Date.now())
+		}
+		return null
+	}
+
+	async cleanupExpired(): Promise<void> {
+		if (import.meta.server) {
+			const prefix = 'cache:'
+			const now = Date.now()
+			const storage = CApplicationCache.storage
+			const keysToDelete: string[] = []
+
+			for (const [key, entry] of storage.entries()) {
+				if (key.startsWith(prefix)) {
+					if (now - entry.timestamp > entry.lifetime) {
+						keysToDelete.push(key)
+					}
+				}
+			}
+
+			for (const key of keysToDelete) {
+				storage.delete(key)
+			}
+		}
+	}
+}

package/services/CacheProvider/CCookieCache.ts

@@ -0,0 +1,212 @@
+import { ACacheProvider } from './ACacheProvider'
+import type { ICacheEntry } from '../types'
+
+export class CCookieCache extends ACacheProvider {
+	private static instance: CCookieCache | null = null
+
+	public static getInstance(): CCookieCache {
+		if (!this.instance) {
+			this.instance = new CCookieCache()
+		}
+		return this.instance
+	}
+
+	public type = 'Cookie'
+
+	private constructor() {
+		super()
+	}
+
+	async getKeyList(nuxtApp?: any): Promise<Array<string>> {
+		const prefix = 'cache:'
+		let cookieStr = ''
+
+		if (import.meta.client) {
+			cookieStr = document.cookie
+		} else if (nuxtApp) {
+			// Extract from H3Event or SSR Context
+			const headers = (nuxtApp as any).node?.req?.headers || (nuxtApp as any).ssrContext?.event?.node?.req?.headers
+			cookieStr = headers?.['cookie'] || ''
+		}
+
+		if (!cookieStr) return []
+
+		const keys: string[] = []
+		const cookies = cookieStr.split(';')
+		for (let i = 0; i < cookies.length; i++) {
+			const cookie = cookies[i].trim()
+			const eqPos = cookie.indexOf('=')
+			if (eqPos > 0) {
+				const name = decodeURIComponent(cookie.substring(0, eqPos))
+				if (name.startsWith(prefix)) {
+					keys.push(name.substring(prefix.length))
+				}
+			}
+		}
+		return keys
+	}
+
+	async get<T>(key: string, nuxtApp?: any): Promise<T | null> {
+		const prefixedKey = 'cache:' + key
+		let cookieValue: string | null = null
+
+		if (import.meta.client) {
+			const name = prefixedKey + '='
+			const ca = document.cookie.split(';')
+			for (let i = 0; i < ca.length; i++) {
+				let c = ca[i].trim()
+				if (c.indexOf(name) === 0) {
+					cookieValue = c.substring(name.length, c.length)
+					break
+				}
+			}
+		} else if (nuxtApp) {
+			const headers = (nuxtApp as any).node?.req?.headers || (nuxtApp as any).ssrContext?.event?.node?.req?.headers
+			const cookieStr = headers?.['cookie'] || ''
+			const name = prefixedKey + '='
+			const ca = cookieStr.split(';')
+			for (let i = 0; i < ca.length; i++) {
+				let c = ca[i].trim()
+				if (c.indexOf(name) === 0) {
+					cookieValue = c.substring(name.length, c.length)
+					break
+				}
+			}
+		}
+
+		if (!cookieValue) return null
+
+		try {
+			const val = JSON.parse(decodeURIComponent(cookieValue)) as ICacheEntry<T>
+			if (val && val.timestamp && val.lifetime) {
+				if (Date.now() - val.timestamp <= val.lifetime) {
+					return val.data
+				} else {
+					// Expired
+					await this.set(key, null as any, 0, nuxtApp)
+				}
+			}
+			return null
+		} catch (e) {
+			return null
+		}
+	}
+
+	async set<T>(key: string, data: T, lifetime: number, nuxtApp?: any): Promise<void> {
+		const prefixedKey = 'cache:' + key
+		const entry: ICacheEntry<T> = {
+			data,
+			timestamp: Date.now(),
+			lifetime
+		}
+
+		const cookieValue = encodeURIComponent(JSON.stringify(entry))
+		const maxAge = Math.floor(lifetime / 1000)
+		const expires = new Date(Date.now() + lifetime).toUTCString()
+		const cookieStr = `${prefixedKey}=${cookieValue}; Max-Age=${maxAge}; Path=/; SameSite=Lax${import.meta.server ? '; HttpOnly' : ''}`
+
+		if (import.meta.client) {
+			document.cookie = cookieStr
+		} else if (nuxtApp) {
+			const res = (nuxtApp as any).node?.res || (nuxtApp as any).ssrContext?.event?.node?.res
+			if (res) {
+				const existing = res.getHeader('Set-Cookie')
+				if (!existing) {
+					res.setHeader('Set-Cookie', cookieStr)
+				} else if (Array.isArray(existing)) {
+					res.setHeader('Set-Cookie', [...existing, cookieStr])
+				} else {
+					res.setHeader('Set-Cookie', [existing as string, cookieStr])
+				}
+			}
+		}
+	}
+
+	async remove(key: string, nuxtApp?: any): Promise<void> {
+		const prefixedKey = 'cache:' + key
+		const cookieStr = `${prefixedKey}=; Max-Age=0; Path=/; SameSite=Lax${import.meta.server ? '; HttpOnly' : ''}`
+
+		if (import.meta.client) {
+			document.cookie = cookieStr
+		} else if (nuxtApp) {
+			const res = (nuxtApp as any).node?.res || (nuxtApp as any).ssrContext?.event?.node?.res
+			if (res) {
+				const existing = res.getHeader('Set-Cookie')
+				if (!existing) {
+					res.setHeader('Set-Cookie', cookieStr)
+				} else if (Array.isArray(existing)) {
+					res.setHeader('Set-Cookie', [...existing, cookieStr])
+				} else {
+					res.setHeader('Set-Cookie', [existing as string, cookieStr])
+				}
+			}
+		}
+	}
+
+	async getRemainingTime(key: string, nuxtApp?: any): Promise<number | null> {
+		const prefixedKey = 'cache:' + key
+		let cookieValue: string | null = null
+
+		if (import.meta.client) {
+			const name = prefixedKey + '='
+			const ca = document.cookie.split(';')
+			for (let i = 0; i < ca.length; i++) {
+				let c = ca[i].trim()
+				if (c.indexOf(name) === 0) {
+					cookieValue = c.substring(name.length, c.length)
+					break
+				}
+			}
+		} else if (nuxtApp) {
+			const headers = (nuxtApp as any).node?.req?.headers || (nuxtApp as any).ssrContext?.event?.node?.req?.headers
+			const cookieStr = headers?.['cookie'] || ''
+			const name = prefixedKey + '='
+			const ca = cookieStr.split(';')
+			for (let i = 0; i < ca.length; i++) {
+				let c = ca[i].trim()
+				if (c.indexOf(name) === 0) {
+					cookieValue = c.substring(name.length, c.length)
+					break
+				}
+			}
+		}
+
+		if (!cookieValue) return null
+
+		try {
+			const val = JSON.parse(decodeURIComponent(cookieValue)) as ICacheEntry<any>
+			if (val && val.timestamp && val.lifetime) {
+				return Math.max(0, (val.timestamp + val.lifetime) - Date.now())
+			}
+			return null
+		} catch (e) {
+			return null
+		}
+	}
+
+	async cleanupExpired(): Promise<void> {
+		if (import.meta.client) {
+			const prefix = 'cache:'
+			const now = Date.now()
+			const cookies = document.cookie.split(';')
+			for (let i = 0; i < cookies.length; i++) {
+				const cookie = cookies[i].trim()
+				const eqPos = cookie.indexOf('=')
+				if (eqPos > 0) {
+					const name = decodeURIComponent(cookie.substring(0, eqPos))
+					if (name.startsWith(prefix)) {
+						const value = decodeURIComponent(cookie.substring(eqPos + 1))
+						try {
+							const entry: ICacheEntry<any> = JSON.parse(value)
+							if (now - entry.timestamp > entry.lifetime) {
+								document.cookie = `${encodeURIComponent(name)}=; max-age=0; path=/`
+							}
+						} catch (e) {
+							document.cookie = `${encodeURIComponent(name)}=; max-age=0; path=/`
+						}
+					}
+				}
+			}
+		}
+	}
+}