Katlux Providers Development

Isomorphic Data, Cache, and Request Providers for state management, client/server side caching, and API data fetching.

The @katlux/providers package is a 100% standalone, zero-framework-dependency TypeScript library. It works seamlessly in Node.js, CLI applications, Vanilla JS, React, Svelte, and Vue 3 / Nuxt 3.

Data Providers: CFlatClientDataProvider, CFlatServerDataProvider, CTreeClientDataProvider, CTreeServerDataProvider, CAPIFlatClientDataProvider, CAPIFlatServerDataProvider - handle client/server filtering, sorting, pagination, and tree hierarchies.
Observer Pattern: Standalone event-driven updates via provider.subscribe((state) => ...) and snapshot retrieval via provider.getState().
Framework-Agnostic State: Access native properties directly (provider.pageData, provider.loading, provider.currentPage, provider.rowCount) with zero framework overhead.
Vue 3 Bridge: Use useDataProvider(provider) from @katlux/toolkit for idiomatic Vue refs with automatic lifecycle cleanup (onScopeDispose) and zero SSR memory leaks.
Cache Providers: Isomorphic caching mechanisms including Cookie, IndexedDB, Memory, LocalStorage, Application Cache, and Session Cache strategies.
Request Providers: Encapsulated API fetchers with automatic retry logic, caching strategies (ECacheStrategy), request deduplication, and error handling.

TEXT

packages/katlux-providers/
├── services/
│   ├── DataProvider/   # ADataProvider, AAPIDataProvider, Flat & Tree providers
│   ├── CacheProvider/  # CMemoryCache, CIndexedDBCache, CLocalStorageCache, etc.
│   ├── RequestProvider/# RequestProvider, RequestQueue, RequestProviderRegistry
│   ├── utils/          # filterLogic, sortLogic, debounce
│   ├── types.ts        # Interfaces, enums & type definitions
│   └── index.ts        # Package export barrel
├── package.json
└── tsconfig.json

Katlux is currently evaluating three complementary state synchronization approaches for developers who need to mirror data provider state into global stores (e.g., Pinia), browser URL query parameters, or local components.

Standalone methods on ADataProvider with zero UI framework dependencies. Ideal for vanilla TypeScript, testing, SSR hydration, and micro-frontend state persistence.

getState(): Returns a clean snapshot of pagination, filters, and sorting.
setState(partial, options): Atomically updates provider state. Supports silent: true to suppress automatic re-fetching.
onStateChange(listener): Subscribes to targeted state changes, returning an unsubscribe function.
serializeState() & deserializeState(): URL-safe query string conversion for bookmarkable search/filter states.

TypeScript

// Pure TypeScript / Node / React / Pinia direct sync:
const state = provider.getState()
// { currentPage: 1, pageSize: 10, filter: null, sortList: [] }

// Direct update:
provider.setState({ currentPage: 2, pageSize: 25 })

// Serialize to URL query string:
const queryStr = provider.serializeState()
// "page=2&pageSize=25"

// Deserialize and restore state:
provider.deserializeState(queryStr)

Connect an existing Pinia store or reactive refs directly to useDataProvider. Bidirectional updates are automatically synchronized with built-in recursion guards to prevent infinite loops.

TypeScript

// 1. Define your Pinia Store
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useCatalogStore = defineStore('catalog', () => {
  const currentPage = ref(1)
  const pageSize = ref(20)
  const filter = ref(null)
  const sortList = ref([])

  return { currentPage, pageSize, filter, sortList }
})

// 2. In your Vue / Nuxt Component:
import { useCatalogStore } from '~/stores/catalog'
import { useDataProvider } from '#toolkit/composables/useDataProvider'
import { storeToRefs } from 'pinia'

const store = useCatalogStore()
const { currentPage, pageSize, filter, sortList } = storeToRefs(store)

// Provider automatically syncs two-way with Pinia:
const { pageData, loading } = useDataProvider(myProvider, {
  currentPage,
  pageSize,
  filter,
  sortList
})

For developers who prefer declarative template bindings without composing store refs manually, all Katlux data components expose native v-model:* props:

Pug

// Two-way bound KDatatable
KDatatable(
  :dataProvider="provider"
  v-model:currentPage="store.currentPage"
  v-model:pageSize="store.pageSize"
  v-model:filter="store.filter"
  v-model:sortList="store.sortList"
  v-model:selectedRows="store.selectedRows"
  v-model:selectAll="store.selectAll"
)

// Standalone or Provider-Bound KPagination
KPagination(
  :dataProvider="provider"
  v-model:currentPage="store.currentPage"
  v-model:pageSize="store.pageSize"
)

// KCombobox with search & virtual scroll awareness
KCombobox(
  :dataProvider="provider"
  v-model:searchtext="searchQuery"
  @scroll-state-change="onScrollStateChange"
)

// KProductList eCommerce Block
KProductList(
  :dataProvider="provider"
  v-model:currentPage="store.currentPage"
  v-model:pageSize="store.pageSize"
)

Approach	Best Suited For	Framework Coupling	Ergonomics	SSR & Hydration
Tier 1: Agnostic Provider State	Micro-frontends, vanilla JS, React/Svelte, SSR serialization	Zero (Pure TypeScript)	Programmatic (imperative)	Excellent (native `serializeState`)
Tier 2: useDataProvider Bridge	Pinia stores, Nuxt 3 composables, reactive state sync	Vue 3 / Nuxt 3	High (auto-subscribing refs)	Automatic (Vue reactive lifecycle)
Tier 3: Component v-model:*	Rapid UI templates, local page state, declarative Pug/HTML	Vue 3 Template	Highest (standard Vue template syntax)	Standard Vue prop hydration