@plyaz/types 1.22.0 → 1.22.2

package/dist/core/frontend/types.d.ts

@@ -13,18 +13,519 @@ import type { CoreBaseServiceConfig, CoreBaseMapperInstance, CoreBaseValidatorIn
 import type { CoreDomainServiceInstance, CoreServiceEntry } from '../init';
 /**
  * Base store interface for frontend services.
- * Stores must implement at least setData/setFlags.
- * Loading and error setters are optional.
+ *
+ * ## Overview
+ * This interface defines the contract between domain services and Zustand stores.
+ * Services call these methods to synchronize state after API operations.
+ *
+ * ## Required Methods
+ * At minimum, stores must implement either `setData` or domain-specific setters
+ * (e.g., `setFlags` for feature flags, `setItems` for collections).
+ *
+ * ## Optional Methods
+ * - `updateData` - For partial/merge updates (recommended for performance)
+ * - `setLoading` - For loading state management (automatically called by services)
+ *
+ * ## Error Handling
+ * **Important**: Error state is handled globally via the error store.
+ * Individual domain stores should NOT have `setError` or `error` state.
+ * Errors are automatically sent to the global error store by base services.
+ *
+ * ## Zustand Implementation Example
+ * ```typescript
+ * import { create } from 'zustand';
+ * import type { CoreBaseFrontendStore } from '@plyaz/types/core';
+ *
+ * interface MyStoreData {
+ *   items: MyEntity[];
+ *   selectedId: string | null;
+ * }
+ *
+ * interface MyStore extends CoreBaseFrontendStore<MyStoreData> {
+ *   items: MyEntity[];
+ *   selectedId: string | null;
+ *   isLoading: boolean;
+ *
+ *   // Required by CoreBaseFrontendStore
+ *   setData: (data: MyStoreData) => void;
+ *   updateData: (data: Partial<MyStoreData>) => void;
+ *   setLoading: (isLoading: boolean) => void;
+ *
+ *   // Domain-specific methods
+ *   addItem: (item: MyEntity) => void;
+ *   updateItem: (id: string, item: MyEntity) => void;
+ *   removeItem: (id: string) => void;
+ * }
+ *
+ * export const useMyStore = create<MyStore>((set) => ({
+ *   items: [],
+ *   selectedId: null,
+ *   isLoading: false,
+ *
+ *   setData: (data) => set({ items: data.items, selectedId: data.selectedId }),
+ *   updateData: (data) => set((state) => ({ ...state, ...data })),
+ *   setLoading: (isLoading) => set({ isLoading }),
+ *
+ *   addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+ *   updateItem: (id, item) => set((state) => ({
+ *     items: state.items.map((i) => (i.id === id ? item : i)),
+ *   })),
+ *   removeItem: (id) => set((state) => ({
+ *     items: state.items.filter((i) => i.id !== id),
+ *   })),
+ * }));
+ * ```
+ *
+ * ## Service Integration
+ * Services automatically call these methods after successful operations:
+ * - After `fetchAll()` → calls `setData()` with full dataset
+ * - After `create()` → service calls custom `addItem()` in `afterCreate` hook
+ * - After `update()` → service calls custom `updateItem()` in `afterUpdate` hook
+ * - Before any operation → calls `setLoading(true)`
+ * - After operation completes → calls `setLoading(false)`
+ *
+ * @typeParam TData - Store data structure (e.g., `{ items: Entity[]; selectedId: string | null }`)
+ *
+ * @see {@link CoreBaseFrontendServiceConfig} for service configuration
+ * @see {@link BaseFrontendDomainService} for service implementation
  */
 export interface CoreBaseFrontendStore<TData = Record<string, unknown>> {
-    /** Set/replace all data in the store */
+    /**
+     * Set/replace all data in the store (full replacement).
+     *
+     * Called by services after operations that return complete datasets,
+     * such as `fetchAll()` or when resetting store state.
+     *
+     * @param data - Complete data object matching TData structure
+     *
+     * @example
+     * ```typescript
+     * setData: (data) => set({ items: data.items, selectedId: data.selectedId })
+     * ```
+     */
     setData?(data: TData): void;
-    /** Update/merge data in the store (optional) */
+    /**
+     * Update/merge data in the store (partial update).
+     *
+     * Called by services for incremental updates. More efficient than `setData`
+     * when only updating specific fields.
+     *
+     * @param data - Partial data object with fields to update
+     *
+     * @example
+     * ```typescript
+     * updateData: (data) => set((state) => ({ ...state, ...data }))
+     * ```
+     */
     updateData?(data: Partial<TData>): void;
-    /** Set loading state (optional) */
+    /**
+     * Set loading state for async operations.
+     *
+     * Automatically called by services:
+     * - `setLoading(true)` before API call
+     * - `setLoading(false)` after completion (success or error)
+     *
+     * @param isLoading - Whether an operation is in progress
+     *
+     * @example
+     * ```typescript
+     * setLoading: (isLoading) => set({ isLoading })
+     * ```
+     */
     setLoading?(isLoading: boolean): void;
-    /** Set error state (optional) */
-    setError?(error: unknown): void;
+}
+/**
+ * Fetcher function type for API operations
+ * Matches FetchResponse structure from fetchff
+ * Uses ServiceOptions from @plyaz/api for config merging
+ */
+export type CoreFetcherFunction<TData = unknown, TResult = unknown, TOptions = unknown> = (data?: TData, options?: TOptions) => Promise<{
+    isSuccess: boolean;
+    data?: TResult;
+    error?: Error | null;
+}>;
+/**
+ * Fetchers configuration for frontend services.
+ *
+ * ## Overview
+ * Defines fetcher functions that services use to make API calls.
+ * Fetchers wrap the API client and handle request/response transformation.
+ *
+ * ## Why Fetchers?
+ * Services should NEVER call `apiClient.get()`, `apiClient.post()`, etc. directly.
+ * Instead, they configure fetchers that:
+ * 1. Encapsulate API endpoints
+ * 2. Handle request/response formatting
+ * 3. Allow for easy mocking in tests
+ * 4. Provide type-safe API calls
+ *
+ * ## Configuration Pattern
+ * ```typescript
+ * class MyService extends BaseFrontendDomainService<...> {
+ *   constructor(config: MyServiceConfig) {
+ *     super({
+ *       serviceConfig: {
+ *         fetchers: {
+ *           fetchAll: async (_, options) =>
+ *             this.apiClient.get<MyDTO[]>('/api/my-entities'),
+ *           create: async (data, options) =>
+ *             this.apiClient.post<MyDTO>('/api/my-entities', data),
+ *           // ... other fetchers
+ *         },
+ *       },
+ *       // ... other config
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * ## Fetcher Function Signature
+ * All fetchers return a Promise with this structure:
+ * ```typescript
+ * Promise<{
+ *   isSuccess: boolean;
+ *   data?: TResult;
+ *   error?: Error | null;
+ * }>
+ * ```
+ *
+ * ## HTTP Methods Supported
+ * - **GET** - `fetchAll`, `fetchById` (read operations)
+ * - **POST** - `create` (create new entity)
+ * - **PUT** - `put` (full entity replacement)
+ * - **PATCH** - `update` (partial entity update)
+ * - **DELETE** - `delete` (remove entity)
+ * - **OPTIONS** - `options` (get allowed methods/CORS headers)
+ * - **HEAD** - `head` (get headers only, no body)
+ *
+ * ## When to Use Each Method
+ * - Use `fetchAll` for listing/querying entities
+ * - Use `fetchById` for retrieving single entities
+ * - Use `create` for POST requests (new entities)
+ * - Use `update` for PATCH requests (most common for updates)
+ * - Use `put` for full replacements (less common)
+ * - Use `delete` for removing entities
+ *
+ * @typeParam TEntity - Domain entity type (internal representation)
+ * @typeParam TResponseDTO - API response DTO type (server format)
+ * @typeParam TCreateDTO - Create request DTO type (for POST)
+ * @typeParam TPatchDTO - Patch request DTO type (for PATCH)
+ * @typeParam TOptions - Options type for fetcher calls (custom config)
+ * @typeParam TDeleteResult - Delete response type (default: unknown - can be confirmation, deleted entity, or void)
+ *
+ * @see {@link CoreFetcherFunction} for the function signature
+ * @see {@link BaseFrontendDomainService} for usage in services
+ *
+ * @example
+ * ```typescript
+ * // Example with all fetchers configured
+ * const fetchers: CoreServiceFetchers<
+ *   Topic,
+ *   TopicDTO,
+ *   CreateTopicDTO,
+ *   PatchTopicDTO,
+ *   QueryTopicDTO
+ * > = {
+ *   fetchAll: async (query, opts) =>
+ *     apiClient.get<TopicDTO[]>('/api/topics', { params: query }),
+ *
+ *   fetchById: async (id, opts) =>
+ *     apiClient.get<TopicDTO>(`/api/topics/${id}`),
+ *
+ *   create: async (data, opts) =>
+ *     apiClient.post<TopicDTO>('/api/topics', data),
+ *
+ *   update: async ({ id, data }, opts) =>
+ *     apiClient.patch<TopicDTO>(`/api/topics/${id}`, data),
+ *
+ *   delete: async (id, opts) => {
+ *     const response = await apiClient.delete(`/api/topics/${id}`);
+ *     return { ...response, data: { success: true } };
+ *   },
+ * };
+ * ```
+ */
+export interface CoreServiceFetchers<TEntity = unknown, TResponseDTO = unknown, TCreateDTO = unknown, TPatchDTO = unknown, TQueryDTO = unknown, TOptions = unknown, TDeleteResult = unknown> {
+    /**
+     * Fetch all entities from API (GET).
+     *
+     * Used by `service.fetchAll(query?)` to retrieve a list/collection.
+     *
+     * @param query - Optional query/filter parameters (e.g., { status: 'active' })
+     * @param options - Optional service options (request config, etc.)
+     * @returns Promise with array of DTOs
+     *
+     * @example
+     * ```typescript
+     * fetchAll: async (query, opts) =>
+     *   apiClient.get<TopicDTO[]>('/api/topics', { params: query })
+     * ```
+     */
+    fetchAll?: CoreFetcherFunction<Partial<TQueryDTO> | undefined, TResponseDTO[], TOptions>;
+    /**
+     * Fetch single entity by ID (GET).
+     *
+     * Used by `service.fetchById(id)` to retrieve one entity.
+     *
+     * @param data - Entity ID (string)
+     * @param options - Optional query params
+     * @returns Promise with single DTO
+     *
+     * @example
+     * ```typescript
+     * fetchById: async (id, opts) =>
+     *   apiClient.get<TopicDTO>(`/api/topics/${id}`)
+     * ```
+     */
+    fetchById?: CoreFetcherFunction<string, TResponseDTO, TOptions>;
+    /**
+     * Create new entity (POST).
+     *
+     * Used by `service.create(data)` to create a new entity.
+     *
+     * @param data - Create DTO (entity data)
+     * @param options - Optional request config
+     * @returns Promise with created entity DTO
+     *
+     * @example
+     * ```typescript
+     * create: async (data, opts) =>
+     *   apiClient.post<TopicDTO>('/api/topics', data)
+     * ```
+     */
+    create?: CoreFetcherFunction<TCreateDTO, TResponseDTO, TOptions>;
+    /**
+     * Update entity - full replacement (PUT).
+     *
+     * Used by `service.put(id, data)` for full entity replacement.
+     * Less common than PATCH - only use when API requires full object.
+     *
+     * @param data - Object with `id` and `data` (full entity)
+     * @param options - Optional request config
+     * @returns Promise with updated entity DTO
+     *
+     * @example
+     * ```typescript
+     * put: async ({ id, data }, opts) =>
+     *   apiClient.put<TopicDTO>(`/api/topics/${id}`, data)
+     * ```
+     */
+    put?: CoreFetcherFunction<{
+        id: string;
+        data: TCreateDTO;
+    }, TResponseDTO, TOptions>;
+    /**
+     * Update entity - partial (PATCH).
+     *
+     * Used by `service.update(id, data)` for partial updates.
+     * Most common update method - only sends changed fields.
+     *
+     * @param data - Object with `id` and `data` (partial entity)
+     * @param options - Optional request config
+     * @returns Promise with updated entity DTO
+     *
+     * @example
+     * ```typescript
+     * update: async ({ id, data }, opts) =>
+     *   apiClient.patch<TopicDTO>(`/api/topics/${id}`, data)
+     * ```
+     */
+    update?: CoreFetcherFunction<{
+        id: string;
+        data: TPatchDTO;
+    }, TResponseDTO, TOptions>;
+    /**
+     * Delete entity (DELETE).
+     *
+     * Used by `service.delete(id)` to remove an entity.
+     * Can return success confirmation, deleted entity, or void.
+     *
+     * @param data - Entity ID (string)
+     * @param options - Optional request config (e.g., soft delete flag)
+     * @returns Promise with delete result (confirmation, deleted entity, or void)
+     *
+     * @example
+     * ```typescript
+     * // Example 1: Return confirmation object
+     * delete: async (id, opts) => {
+     *   const response = await apiClient.delete(`/api/topics/${id}`);
+     *   return { ...response, data: { success: true, message: 'Deleted' } };
+     * }
+     *
+     * // Example 2: Return deleted entity
+     * delete: async (id, opts) =>
+     *   apiClient.delete<TopicDTO>(`/api/topics/${id}`) // Server returns deleted entity
+     *
+     * // Example 3: Return void (204 No Content)
+     * delete: async (id, opts) => {
+     *   const response = await apiClient.delete(`/api/topics/${id}`);
+     *   return { ...response, data: undefined };
+     * }
+     * ```
+     */
+    delete?: CoreFetcherFunction<string, TDeleteResult, TOptions>;
+    /**
+     * Options request (OPTIONS).
+     *
+     * Used to discover allowed HTTP methods and CORS headers.
+     * Rarely implemented in domain services.
+     *
+     * @param data - Optional URL or resource identifier
+     * @param options - Optional request config
+     * @returns Promise with allowed methods/headers metadata
+     */
+    options?: CoreFetcherFunction<string | undefined, unknown, TOptions>;
+    /**
+     * Head request (HEAD).
+     *
+     * Used to get headers without response body (e.g., check if resource exists).
+     * Rarely implemented in domain services.
+     *
+     * @param data - Optional URL or resource identifier
+     * @param options - Optional request config
+     * @returns Promise with void (only headers, no body)
+     */
+    head?: CoreFetcherFunction<string | undefined, void, TOptions>;
+}
+/**
+ * Store handlers configuration for customizing store synchronization.
+ *
+ * ## Overview
+ * Allows services to customize how data is synced to Zustand stores.
+ * By default, services call `setData()`, `updateData()`, and `setLoading()`.
+ * Store handlers let you override this behavior with custom logic.
+ *
+ * ## Use Cases
+ * - **Custom store methods**: Use store-specific methods instead of generic ones
+ * - **Disable sync**: Turn off store updates completely for manual control
+ * - **Complex transformations**: Transform data before syncing to store
+ * - **Deep nested updates**: Update nested paths in store state
+ *
+ * ## Configuration Pattern
+ * ```typescript
+ * class MyService extends BaseFrontendDomainService<...> {
+ *   constructor(config: MyServiceConfig) {
+ *     super({
+ *       serviceConfig: {
+ *         // Custom handlers
+ *         storeHandlers: {
+ *           setData: (store, data) => store.setMyCustomItems(data.items),
+ *           updateData: (store, data) => store.mergeMyItems(data.items),
+ *           setLoading: (store, isLoading) => store.setIsMyLoading(isLoading),
+ *         },
+ *         // Or disable completely
+ *         // storeHandlers: { disabled: true },
+ *       },
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * ## Default Behavior (if not configured)
+ * When `storeHandlers` is not provided, services use:
+ * - `store.setData(data)` - for full replacement
+ * - `store.updateData(data)` - for partial updates (if available)
+ * - `store.setLoading(isLoading)` - for loading state
+ *
+ * ## Disabling Store Sync
+ * Set `disabled: true` to prevent all store updates.
+ * Useful for services that manage state manually or use different patterns.
+ *
+ * @typeParam TStore - Store interface type
+ * @typeParam TData - Data type for store sync
+ *
+ * @see {@link CoreBaseFrontendStore} for store interface
+ * @see {@link CoreBaseFrontendServiceConfig} for service configuration
+ *
+ * @example
+ * ```typescript
+ * // Example 1: Custom store methods
+ * const handlers: CoreStoreHandlers<CampaignStoreData, CampaignStore> = {
+ *   setData: (store, data) => store.setCampaigns(data.campaigns),
+ *   updateData: (store, data) => store.mergeCampaigns(data.campaigns),
+ *   setLoading: (store, isLoading) => store.setIsCampaignsLoading(isLoading),
+ * };
+ *
+ * // Example 2: Disable store sync
+ * const handlers: CoreStoreHandlers<MyData, MyStore> = {
+ *   disabled: true,
+ * };
+ *
+ * // Example 3: Complex transformation
+ * const handlers: CoreStoreHandlers<TopicStoreData, TopicStore> = {
+ *   setData: (store, data) => {
+ *     // Transform data before syncing
+ *     const sorted = [...data.topics].sort((a, b) => a.order - b.order);
+ *     store.setTopics(sorted);
+ *     store.setLastSync(new Date());
+ *   },
+ * };
+ * ```
+ */
+export interface CoreStoreHandlers<TData = Record<string, unknown>, TStore extends CoreBaseFrontendStore<TData> = CoreBaseFrontendStore<TData>> {
+    /**
+     * Disable all store synchronization.
+     *
+     * When true, the service will not call any store methods.
+     * Useful for manual state management or non-reactive patterns.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Custom handler for setting full data.
+     *
+     * Replaces the default `store.setData(data)` call.
+     * Called during `fetchAll()` and other operations that replace full state.
+     *
+     * @param store - Store instance
+     * @param data - Full data to set
+     *
+     * @example
+     * ```typescript
+     * setData: (store, data) => {
+     *   store.setItems(data.items);
+     *   store.setLastFetch(Date.now());
+     * }
+     * ```
+     */
+    setData?: (store: TStore, data: TData) => void;
+    /**
+     * Custom handler for partial data updates.
+     *
+     * Replaces the default `store.updateData(data)` call.
+     * Called during operations that merge/update partial state.
+     *
+     * @param store - Store instance
+     * @param data - Partial data to merge
+     *
+     * @example
+     * ```typescript
+     * updateData: (store, data) => {
+     *   if (data.items) store.mergeItems(data.items);
+     *   if (data.selectedId) store.setSelectedId(data.selectedId);
+     * }
+     * ```
+     */
+    updateData?: (store: TStore, data: Partial<TData>) => void;
+    /**
+     * Custom handler for loading state.
+     *
+     * Replaces the default `store.setLoading(isLoading)` call.
+     * Called before and after all CRUD operations.
+     *
+     * @param store - Store instance
+     * @param isLoading - Loading state
+     *
+     * @example
+     * ```typescript
+     * setLoading: (store, isLoading) => {
+     *   store.setIsItemsLoading(isLoading);
+     *   if (isLoading) store.clearError();
+     * }
+     * ```
+     */
+    setLoading?: (store: TStore, isLoading: boolean) => void;
 }
 /**
  * Configuration for frontend domain services
@@ -40,6 +541,31 @@ export interface CoreBaseFrontendServiceConfig<TData = Record<string, unknown>,
      * If not specified, no stores are connected (warning logged).
      */
     storeKeys?: StoreKey[];
+    /** API base path for endpoints (e.g., '/api/examples') */
+    apiBasePath?: string;
+    /** Fetcher functions for API operations (replaces direct apiClient usage) */
+    fetchers?: CoreServiceFetchers<unknown, unknown, unknown, unknown, unknown, unknown, unknown>;
+    /**
+     * Store handlers for customizing store synchronization.
+     *
+     * Allows services to override default store sync behavior with custom logic.
+     * Useful for custom store methods, complex transformations, or disabling sync.
+     *
+     * @see {@link CoreStoreHandlers} for configuration options
+     *
+     * @example
+     * ```typescript
+     * // Custom handlers
+     * storeHandlers: {
+     *   setData: (store, data) => store.setCustomItems(data.items),
+     *   updateData: (store, data) => store.mergeCustomItems(data.items),
+     * }
+     *
+     * // Disable sync
+     * storeHandlers: { disabled: true }
+     * ```
+     */
+    storeHandlers?: CoreStoreHandlers<TData, TStore>;
 }
 /**
  * Base interface for frontend domain services with store integration.
@@ -193,7 +719,17 @@ export interface CoreFeatureFlagStoreInitConfig {
  * Base service config for frontend services (constructor config)
  */
 export interface CoreBaseFrontendServiceConstructorConfig<TConfig extends CoreBaseFrontendServiceConfig<TData, TStore>, TStore extends CoreBaseFrontendStore<TData>, TData = Record<string, unknown>, TMapper extends CoreBaseMapperInstance = CoreBaseMapperInstance, TValidator extends CoreBaseValidatorInstance = CoreBaseValidatorInstance> extends CoreBaseServiceConfig<TConfig, TMapper, TValidator> {
-    /** Data key used for store sync (e.g., 'flags', 'items', 'data') */
+    /**
+     * Data key used for store sync - indicates which property in the store contains the primary data.
+     *
+     * Examples:
+     * - For feature flags: 'flags' (store has flags property)
+     * - For items/entities: 'items' (store has items property)
+     * - For nested data: 'nested.items' (store has nested.items)
+     *
+     * This is used as metadata and for potential helper methods.
+     * For custom sync behavior, use `storeHandlers` in serviceConfig instead.
+     */
     storeDataKey?: string;
 }
 /**

package/dist/core/index.d.ts

@@ -18,4 +18,5 @@ export type * from './types';
 export type * from './domain';
 export type * from './init';
 export type * from './services';
+export { SERVICE_KEYS, ALL_SERVICE_KEYS } from './services';
 export type * from './frontend';

package/dist/core/init/index.d.ts

@@ -2,4 +2,4 @@
  * Core Init Types
  * Service registry and initialization type definitions
  */
-export type { CoreDomainServiceInstance, CoreServiceInitConfig, CoreServiceCreateOptions, CoreInitializableDomainService, CoreServiceEntry, CoreServiceRegistryConfig, CoreExtractServiceConfig, CoreExtractServiceInstance, CoreFeatureFlagInitConfig, CoreErrorHandlerInitConfig, CoreInitOptionsBase, CoreServicesResultBase, } from './types';
+export type { CoreDomainServiceInstance, CoreServiceInitConfig, CoreServiceCreateOptions, CoreInitializableDomainService, CoreServiceEntry, CoreServiceRegistryConfig, CoreExtractServiceConfig, CoreExtractServiceInstance, CoreFeatureFlagInitConfig, CoreErrorHandlerInitConfig, CoreCacheConfig, CoreInitOptionsBase, CoreServicesResultBase, } from './types';