@plyaz/core 1.2.0 → 1.2.1

package/dist/domain/base/BaseFrontendDomainService.d.ts

@@ -0,0 +1,493 @@
+/**
+ * Base Frontend Domain Service
+ *
+ * Extends BaseDomainService with common frontend patterns:
+ * - **Primary/Read Store Pattern**: Services have ONE primary store (mutate) + multiple read stores (read-only)
+ * - **Automatic Store Injection**: Stores injected by ServiceRegistry from root store
+ * - **Automatic Loading State**: Managed via setStoresLoading() on primary store
+ * - **Generic CRUD Operations**: With fetchers from @plyaz/api
+ * - **Event Emission**: Typed event payloads via CoreEventManager
+ * - **Automatic DTO Mapping**: Via mapper classes
+ *
+ * ## Store Architecture (NEW)
+ *
+ * ### Primary Store (Mutate)
+ * - Service has ONE primary store defined by `store: 'campaigns'` config
+ * - Can call: setData(), updateData(), setLoading()
+ * - syncToStores() syncs ONLY to primary store
+ * - Access via: this.primaryStore
+ *
+ * ### Read Stores (Read-Only)
+ * - Service can read from multiple stores: `readStores: ['users', 'error', 'featureFlags']`
+ * - Can read state but should NOT call mutation methods
+ * - Used for cross-domain data access (e.g., campaign service reading user data)
+ * - Access via: this.getReadStore('users')
+ *
+ * ### All Stores from Root Store
+ * - All stores (domain + global) are slices of ONE root Zustand store
+ * - Automatically reactive - changes propagate to subscribers (React components)
+ * - Error/featureFlags are built-in, domain stores added dynamically
+ *
+ * Frontend domain services should extend this class instead of BaseDomainService
+ * to get automatic store integration and CRUD capabilities.
+ *
+ * All generic type parameters for full type safety:
+ * - TConfig: Service configuration type
+ * - TStore: Store interface type
+ * - TData: Data type for store sync
+ * - TEntity: Domain entity type
+ * - TResponseDTO: API response DTO type (snake_case)
+ * - TCreateDTO: Create request DTO type
+ * - TPatchDTO: Patch request DTO type (partial update)
+ * - TQueryDTO: Query/filter DTO type for fetchAll
+ * - TStoreState: Serializable store state type
+ * - TMapper: Mapper instance type
+ * - TValidator: Optional validator type
+ *
+ * @example
+ * ```typescript
+ * class MyFrontendService extends BaseFrontendDomainService<
+ *   MyConfig,
+ *   MyStore,
+ *   MyStoreData,
+ *   MyEntity,
+ *   MyResponseDTO,
+ *   CreateMyDTO,
+ *   PatchMyDTO,
+ *   QueryMyDTO,
+ *   MyStoreState,
+ *   MyMapper
+ * > {
+ *   protected eventPrefix = 'myDomain';
+ *   protected mapper: MyMapper;
+ *
+ *   constructor(config: MyConfig) {
+ *     super({ ... mapperClass: MyMapperClass });
+ *     this.mapper = new MyMapperClass();
+ *   }
+ *
+ *   // All CRUD methods inherited!
+ *   // - fetchAll(query?)
+ *   // - fetchById(id)
+ *   // - create(data)
+ *   // - update(id, data)
+ *   // - delete(id)
+ * }
+ * ```
+ */
+import { BaseDomainService } from '../../domain/base';
+import { CorePackageError } from '@plyaz/errors';
+import type { RootStoreSlice } from '@plyaz/types/store';
+import type { CoreEntityCreatingPayload, CoreEntityCreatedPayload, CoreEntityPatchingPayload, CoreEntityPatchedPayload, CoreEntityDeletingPayload, CoreEntityDeletedPayload, CoreEntityErrorPayload, CoreEntityCompletePayload } from '@plyaz/types/core';
+export type { CoreBaseFrontendStore, CoreBaseFrontendServiceConfig, CoreBaseFrontendServiceConstructorConfig, CoreStoreHandlers, } from '@plyaz/types/core';
+import type { CoreBaseFrontendStore, CoreBaseFrontendServiceConfig, CoreBaseFrontendServiceConstructorConfig, CoreBaseMapperInstance, CoreBaseValidatorInstance, CoreStoreHandlers, CoreOptimisticUpdateConfig } from '@plyaz/types/core';
+/**
+ * Base type for frontend event payloads
+ * All frontend event payloads should extend this
+ */
+type BaseFrontendEventPayload = CoreEntityCreatingPayload<unknown> | CoreEntityCreatedPayload<unknown, unknown> | CoreEntityPatchingPayload<unknown> | CoreEntityPatchedPayload<unknown, unknown> | CoreEntityDeletingPayload | CoreEntityDeletedPayload | CoreEntityErrorPayload | CoreEntityCompletePayload | Record<string, unknown>;
+/**
+ * Abstract base class for frontend domain services with store integration and CRUD operations.
+ *
+ * Extends BaseDomainService with:
+ * - Multi-store connection management
+ * - Automatic sync to connected stores
+ * - Loading/error state propagation
+ * - Generic CRUD operations (fetchAll, fetchById, create, update, delete)
+ * - Event emission with typed payloads
+ * - Automatic DTO mapping via mapper
+ *
+ * @typeParam TConfig - Service configuration type
+ * @typeParam TStore - Store interface type
+ * @typeParam TData - Data type for store sync
+ * @typeParam TEntity - Domain entity type
+ * @typeParam TResponseDTO - API response DTO type
+ * @typeParam TCreateDTO - Create request DTO type
+ * @typeParam TPatchDTO - Patch request DTO type
+ * @typeParam TQueryDTO - Query/filter DTO type for fetchAll (default: unknown)
+ * @typeParam TStoreState - Serializable store state type
+ * @typeParam TMapper - Mapper instance type
+ * @typeParam TValidator - Optional validator type
+ * @typeParam TDeleteResult - Delete operation result type (default: void for backwards compatibility)
+ */
+export declare abstract class BaseFrontendDomainService<TConfig extends CoreBaseFrontendServiceConfig<TData, TStore>, TStore extends CoreBaseFrontendStore<TData>, TData = Record<string, unknown>, TEntity = unknown, TResponseDTO = unknown, TCreateDTO = unknown, TPatchDTO extends Partial<unknown> = Partial<TCreateDTO>, TQueryDTO = unknown, TStoreState = TEntity, TMapper extends CoreBaseMapperInstance<TEntity, TResponseDTO, TCreateDTO, TCreateDTO, TPatchDTO, unknown, TStoreState> = CoreBaseMapperInstance<TEntity, TResponseDTO, TCreateDTO, TCreateDTO, TPatchDTO, unknown, TStoreState>, TValidator extends CoreBaseValidatorInstance = CoreBaseValidatorInstance, TDeleteResult = void> extends BaseDomainService<TConfig, TMapper, TValidator> {
+    /**
+     * Event prefix for all events emitted by this service
+     * E.g., 'example' → emits 'example:creating', 'example:created', etc.
+     *
+     * Required by subclasses
+     */
+    protected abstract eventPrefix: string;
+    /** Primary store - the main store this service can mutate */
+    private _primaryStore;
+    /**
+     * Primary store key - override in subclass to set default
+     * @example protected primaryStoreKey = STORE_KEYS.EXAMPLE;
+     */
+    protected primaryStoreKey?: string;
+    /** Read-only stores - can read but not mutate */
+    private readonly _readStores;
+    /**
+     * Read-only store keys - always includes error and featureFlags by default
+     * Override in subclass to add additional read stores
+     * @example protected readStoreKeys = [...super.readStoreKeys, STORE_KEYS.CAMPAIGNS];
+     */
+    protected readStoreKeys: string[];
+    /** Store handlers for custom store synchronization */
+    protected readonly storeHandlers?: CoreStoreHandlers<TData, TStore>;
+    /** Optimistic update configuration */
+    protected readonly optimisticConfig?: CoreOptimisticUpdateConfig;
+    /** Stack of previous states for rollback (LIFO) */
+    private readonly _rollbackStack;
+    /** Maximum rollback stack size */
+    private readonly _maxRollbackStackSize;
+    constructor(config: CoreBaseFrontendServiceConstructorConfig<TConfig, TStore, TData, TMapper, TValidator>);
+    /**
+     * Get the number of connected stores (primary + read stores).
+     */
+    get connectedStoreCount(): number;
+    /**
+     * Check if any stores are connected (primary or read).
+     */
+    get hasConnectedStores(): boolean;
+    /**
+     * Get primary store (protected).
+     * This is the store the service can mutate.
+     */
+    protected get primaryStore(): TStore | null;
+    /**
+     * Get a read-only store by key (protected).
+     * Can read state but should not call mutation methods.
+     *
+     * @param key - Store key (type-safe)
+     * @returns Store slice or undefined (auto-typed based on key)
+     */
+    protected getReadStore<K extends keyof RootStoreSlice>(key: K): RootStoreSlice[K] | undefined;
+    /**
+     * Get a specific store slice by key (protected).
+     *
+     * **Namespaced Root Store Architecture:**
+     * - All stores are slices merged into ONE Zustand root store
+     * - Each slice is namespaced (e.g., store.example, store.errors)
+     * - This returns the SPECIFIC slice for the given key
+     * - Type-safe: only valid store keys allowed
+     *
+     * **Usage Guidelines:**
+     * - Can mutate stores that are NOT in readStoreKeys
+     * - Should NOT mutate stores in readStoreKeys (errors, featureFlags by default)
+     * - Useful for cross-domain updates (e.g., campaign service updating user stats)
+     *
+     * @param key - Store key (type-safe: 'example' | 'errors' | 'featureFlags')
+     * @returns Specific store slice (fully typed based on key)
+     *
+     * @example
+     * ```typescript
+     * // In CampaignService
+     * protected async afterCreate(id: string, campaign: Campaign) {
+     *   // Update primary store (campaigns)
+     *   this.primaryStore.addItem(campaign);
+     *
+     *   // Check feature flag (read-only) - auto-typed as FeatureFlagStoreSlice
+     *   const flagsSlice = this.getStore('featureFlags');  // ✅ Type-safe!
+     *   if (flagsSlice?.flags?.['update-user-stats']) {
+     *     // Update user store (cross-domain mutation - OK since not read-only)
+     *     const userSlice = this.getStore('users');  // ✅ Auto-typed!
+     *     userSlice?.incrementCampaignCount(campaign.userId);
+     *   }
+     * }
+     * ```
+     */
+    protected getStore<K extends keyof RootStoreSlice>(key: K): RootStoreSlice[K] | undefined;
+    /**
+     * Sync data to primary store only (read stores are NOT updated).
+     * Uses setData (replace) or updateData (merge) based on `replace` parameter.
+     * If custom store handlers are configured, uses those instead of default behavior.
+     *
+     * @param data - Data to sync to primary store
+     * @param replace - If true, calls setData; if false, calls updateData
+     */
+    protected syncToStores(data: TData, replace?: boolean): void;
+    /**
+     * Set loading state on primary store only.
+     * Read stores are NOT affected.
+     *
+     * Automatically called by CRUD methods before and after API calls.
+     *
+     * @param isLoading - Loading state
+     */
+    protected setStoresLoading(isLoading: boolean): void;
+    /**
+     * Add entity to store (for create operations).
+     * Priority: storeHandlers.addData > store.addData
+     *
+     * @param entity - Entity to add
+     * @returns The converted store state (for reuse in event payloads)
+     */
+    protected addEntityToStore(entity: TEntity): TStoreState;
+    /**
+     * Update entity in store (for update operations).
+     * Priority: storeHandlers.updateDataById > store.updateDataById
+     *
+     * @param id - Entity ID
+     * @param entity - Updated entity
+     * @returns The converted store state (for reuse in event payloads)
+     */
+    protected updateEntityInStore(id: string, entity: TEntity): TStoreState;
+    /**
+     * Sync multiple entities to store using mapper.toStoreStateList.
+     * Converts entities to store format and syncs via setData (full replacement).
+     *
+     * @param entities - Entities to sync
+     * @returns Array of converted store states
+     */
+    protected syncEntitiesToStore(entities: TEntity[]): TStoreState[];
+    /**
+     * Remove entity from store by ID.
+     * Priority: storeHandlers.removeData > store.removeData
+     *
+     * @param id - Entity ID to remove
+     */
+    protected removeEntityFromStore(id: string): void;
+    /**
+     * Check if optimistic updates are enabled for an operation.
+     */
+    protected isOptimisticEnabled(operation: 'create' | 'update' | 'delete'): boolean;
+    /**
+     * Save current store state for potential rollback.
+     * Call this BEFORE making optimistic changes.
+     */
+    protected saveStateForRollback(operation: string): void;
+    /**
+     * Rollback to previous state on error.
+     * Call this when an optimistic update fails.
+     */
+    protected rollbackState(operation: string, error: Error): void;
+    /**
+     * Clear rollback state after successful operation.
+     * Call this when API succeeds.
+     */
+    protected clearRollbackState(operation: string): void;
+    /**
+     * Resolve conflict between optimistic and server state.
+     */
+    protected resolveConflict<T>(optimistic: T, server: T): T;
+    /**
+     * Fetch all entities from API
+     *
+     * Flow:
+     * 1. Assert service is ready
+     * 2. Check fetcher is available
+     * 3. Set stores loading
+     * 4. Emit 'fetching' event
+     * 5. Lifecycle hook: beforeFetchAll
+     * 6. Call fetcher (from @plyaz/api)
+     * 7. Map response DTOs to domain entities
+     * 8. Lifecycle hook: afterFetchAll
+     * 9. Emit 'fetched' event
+     * 10. Return entities
+     *
+     * Error Handling:
+     * - On API error: wrap and emit error event
+     * - Set error on all stores
+     * - Re-throw wrapped error
+     *
+     * @param query - Optional query/filter parameters (e.g., { status: 'active' })
+     * @param options - Optional service options for fetcher
+     * @returns Promise resolving to array of entities
+     * @throws CorePackageError if fetcher not configured or API call fails
+     *
+     * @example
+     * ```typescript
+     * // Fetch all entities
+     * const allItems = await service.fetchAll();
+     *
+     * // Fetch with filters
+     * const activeItems = await service.fetchAll({ status: 'active' });
+     *
+     * // Fetch with pagination
+     * const pagedItems = await service.fetchAll({ page: 2, limit: 10 });
+     * ```
+     */
+    fetchAll(query?: Partial<TQueryDTO>, options?: unknown): Promise<TEntity[]>;
+    /**
+     * Fetch single entity by ID from API
+     *
+     * @param id - Entity ID
+     * @param options - Optional service options for fetcher
+     * @returns Entity or null if not found
+     * @throws CorePackageError if fetcher not configured or API call fails
+     */
+    fetchById<TInput = string, TOptions = unknown>(id: TInput, options?: TOptions): Promise<TEntity | null>;
+    /**
+     * Create new entity
+     *
+     * Flow:
+     * 1. Assert service is ready
+     * 2. Check fetcher is available
+     * 3. Set stores loading
+     * 4. Emit 'creating' event
+     * 5. Lifecycle hook: beforeCreate
+     * 6. Map input data to create DTO (if mapper available)
+     * 7. [Optimistic] Save state and add to store BEFORE API call
+     * 8. Call create fetcher (from @plyaz/api)
+     * 9. Map response DTO to domain entity
+     * 10. [Optimistic] Resolve conflicts if needed
+     * 11. Lifecycle hook: afterCreate
+     * 12. Emit 'created' event
+     * 13. Return entity
+     *
+     * @param data - Create data (can be partial domain entity or DTO)
+     * @param options - Optional service options for fetcher
+     * @returns Created entity
+     * @throws CorePackageError if fetcher not configured or creation fails
+     */
+    create<TInput = unknown, TOptions = unknown>(data: TInput, options?: TOptions): Promise<TEntity>;
+    /**
+     * Update entity (partial update - PATCH)
+     *
+     * @param id - Entity ID
+     * @param data - Partial update data
+     * @param options - Optional service options for fetcher
+     * @returns Updated entity
+     * @throws CorePackageError if fetcher not configured or update fails
+     */
+    update<TInput = unknown, TOptions = unknown>(id: string, data: TInput, options?: TOptions): Promise<TEntity>;
+    /**
+     * Delete entity
+     *
+     * @param id - Entity ID
+     * @param options - Optional service options for fetcher
+     * @returns Delete operation result (type specified by TDeleteResult generic)
+     * @throws CorePackageError if fetcher not configured or deletion fails
+     */
+    delete<TInput = string, TOptions = unknown>(id: TInput, options?: TOptions): Promise<TDeleteResult>;
+    /**
+     * Emit event with automatic prefix
+     * Uses CoreEventManager under the hood
+     *
+     * @param event - Event name (without prefix)
+     * @param payload - Event payload
+     *
+     * @example
+     * ```typescript
+     * // If eventPrefix is 'example', this emits 'example:created'
+     * this.emitEvent('created', { entity, storeState });
+     * ```
+     */
+    protected emitEvent<TPayload extends BaseFrontendEventPayload>(event: string, payload: TPayload): void;
+    /**
+     * Called before fetchAll API call
+     * Override to add custom logic (e.g., cache check, validate query)
+     *
+     * @param query - Optional query/filter parameters
+     */
+    protected beforeFetchAll?(query?: Partial<TQueryDTO>): Promise<void>;
+    /**
+     * Called after fetchAll success
+     * Override to add custom logic (e.g., cache set, transform entities)
+     *
+     * @param entities - Fetched entities
+     * @param query - Optional query/filter parameters that were used
+     */
+    protected afterFetchAll?(entities: TEntity[], query?: Partial<TQueryDTO>): Promise<void>;
+    /**
+     * Called before fetchById API call
+     */
+    protected beforeFetchById?<TInput>(id: TInput): Promise<void>;
+    /**
+     * Called after fetchById success
+     */
+    protected afterFetchById?(entity: TEntity): Promise<void>;
+    /**
+     * Called before create API call
+     * Use this to modify data or validate before sending to API
+     */
+    protected beforeCreate?<TInput>(data: TInput): Promise<void>;
+    /**
+     * Called after create success
+     * Use this to update stores, show notifications, etc.
+     */
+    protected afterCreate?(entity: TEntity): Promise<void>;
+    /**
+     * Called before update API call
+     */
+    protected beforeUpdate?<TInput>(id: string, data: TInput): Promise<void>;
+    /**
+     * Called after update success
+     */
+    protected afterUpdate?(id: string, entity: TEntity): Promise<void>;
+    /**
+     * Called before delete API call
+     */
+    protected beforeDelete?<TInput>(id: TInput): Promise<void>;
+    /**
+     * Called after delete success
+     */
+    protected afterDelete?<TInput>(id: TInput): Promise<void>;
+    /**
+     * Called before OPTIONS request
+     *
+     * Use for custom logic before checking allowed methods/CORS headers.
+     *
+     * @param resource - Optional resource identifier or URL
+     */
+    protected beforeOptions?<TInput>(resource?: TInput): Promise<void>;
+    /**
+     * Called after OPTIONS request success
+     *
+     * Use for processing allowed methods/headers or logging.
+     *
+     * @param resource - Optional resource identifier or URL
+     * @param result - The OPTIONS response (allowed methods, CORS headers, etc.)
+     */
+    protected afterOptions?<TInput>(resource: TInput | undefined, result: unknown): Promise<void>;
+    /**
+     * Called before HEAD request
+     *
+     * Use for custom logic before checking resource existence/headers.
+     *
+     * @param resource - Optional resource identifier or URL
+     */
+    protected beforeHead?<TInput>(resource?: TInput): Promise<void>;
+    /**
+     * Called after HEAD request success
+     *
+     * Use for processing response headers or logging.
+     * Note: HEAD requests return no body, only headers.
+     *
+     * @param resource - Optional resource identifier or URL
+     * @param headers - Response headers (if available)
+     */
+    protected afterHead?<TInput>(resource: TInput | undefined, headers?: unknown): Promise<void>;
+    /**
+     * Wrap error in CorePackageError with context
+     *
+     * @param error - Original error
+     * @param operation - Operation that failed
+     * @param context - Additional context
+     * @returns Wrapped error
+     */
+    protected wrapError(error: unknown, operation: string, context?: Record<string, unknown>): CorePackageError;
+    /**
+     * Track a frontend operation with observability (span + metrics).
+     * Wraps an operation with automatic span creation, duration recording, and error tracking.
+     *
+     * @param operation - Operation name (fetchAll, fetchById, create, delete)
+     * @param entityId - Optional entity ID for context
+     * @param fn - The operation function to execute
+     * @returns Result of the operation
+     *
+     * @example
+     * ```typescript
+     * const entity = await this.trackOperation('create', undefined, async () => {
+     *   return await this.config.fetchers.create(data);
+     * });
+     * ```
+     */
+    protected trackOperation<T>(operation: 'fetchAll' | 'fetchById' | 'create' | 'patch' | 'delete', entityId: string | undefined, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Record operation metrics (duration and count).
+     */
+    private recordOperationMetrics;
+}
+//# sourceMappingURL=BaseFrontendDomainService.d.ts.map

package/dist/domain/base/BaseFrontendDomainService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseFrontendDomainService.d.ts","sourceRoot":"","sources":["../../../src/domain/base/BaseFrontendDomainService.ts"],"names":[],"mappings":"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"}

package/dist/domain/base/BaseMapper.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Base Mapper
+ *
+ * Abstract base class for domain mappers handling data transformation.
+ * Supports all HTTP operations with corresponding mapping methods.
+ *
+ * Mapping concerns:
+ * - Request mapping (domain → API DTO for POST, PUT, PATCH, DELETE)
+ * - Response mapping (API DTO → domain)
+ * - Store mapping (domain ↔ Zustand state)
+ * - Query mapping (filters → query params)
+ *
+ * Note: Validation is handled by BaseValidator, not here.
+ *
+ * @example
+ * ```typescript
+ * class ExampleMapper extends BaseMapper<
+ *   ExampleEntity,      // Domain model
+ *   ExampleResponseDTO, // API response
+ *   CreateExampleDTO,   // POST body
+ *   UpdateExampleDTO,   // PUT body
+ *   PatchExampleDTO,    // PATCH body
+ *   QueryExampleDTO,    // GET params
+ *   ExampleStoreItem    // Store state
+ * > {
+ *   toDomain(dto) { ... }
+ *   toCreateDTO(data) { ... }
+ *   // ... implement needed methods
+ * }
+ * ```
+ */
+import type { CoreBaseMapperInstance } from '@plyaz/types/core';
+/**
+ * Abstract base mapper with default implementations
+ *
+ * Required to implement:
+ * - toDomain(dto): Convert API response to domain model
+ *
+ * Optional to implement (based on your needs):
+ * - toCreateDTO(data): For POST requests
+ * - toUpdateDTO(data): For PUT requests
+ * - toPatchDTO(data): For PATCH requests
+ * - toQueryDTO(filters): For GET query params
+ * - toStoreState(domain): Custom store state shape
+ * - fromStoreState(state): Restore domain from store
+ */
+export declare abstract class BaseMapper<TDomain, TResponseDTO, TCreateDTO = unknown, TUpdateDTO = TCreateDTO, TPatchDTO = Partial<TCreateDTO>, TQueryDTO = unknown, TStoreState = TDomain> implements CoreBaseMapperInstance<TDomain, TResponseDTO, TCreateDTO, TUpdateDTO, TPatchDTO, TQueryDTO, TStoreState> {
+    /**
+     * Convert API response DTO to domain model
+     * Handle snake_case → camelCase, add computed properties
+     */
+    abstract toDomain(dto: TResponseDTO): TDomain;
+    /**
+     * Convert domain data to create DTO (POST body)
+     * Handle camelCase → snake_case, pick required fields
+     */
+    toCreateDTO?(data: Partial<TDomain>): TCreateDTO;
+    /**
+     * Convert domain data to update DTO (PUT body - full replacement)
+     * Default: same as toCreateDTO
+     */
+    toUpdateDTO?(data: Partial<TDomain>): TUpdateDTO;
+    /**
+     * Convert domain data to patch DTO (PATCH body - partial)
+     * Default: picks only defined fields
+     */
+    toPatchDTO?(data: Partial<TDomain>): TPatchDTO;
+    /**
+     * Convert filter object to query params DTO (GET)
+     * Handle pagination, sorting, filtering
+     */
+    toQueryDTO?(filters: Partial<TQueryDTO>): TQueryDTO;
+    /**
+     * Convert database row/repository result to response DTO
+     * Override to map repository output to API response format
+     * Useful when repository returns different format than API expects
+     */
+    toResponseDTO?(row: unknown): TResponseDTO;
+    /**
+     * Map array of DTOs to domain models
+     */
+    toDomainList(dtos: TResponseDTO[]): TDomain[];
+    /**
+     * Convert domain model to store state (serializable)
+     * Default: strips functions, keeps data
+     */
+    toStoreState(domain: TDomain): TStoreState;
+    /**
+     * Convert array of domain models to aggregated store state
+     * Override to customize how multiple items map to store
+     * Default: returns array of individual store states (as Partial since shape may differ)
+     */
+    toStoreStateList?(domains: TDomain[]): Partial<TStoreState>;
+    /**
+     * Restore domain model from store state
+     * Override to restore computed properties/methods
+     */
+    fromStoreState(state: TStoreState): TDomain;
+}
+//# sourceMappingURL=BaseMapper.d.ts.map

package/dist/domain/base/BaseMapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseMapper.d.ts","sourceRoot":"","sources":["../../../src/domain/base/BaseMapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE;;;;;;;;;;;;;GAaG;AACH,8BAAsB,UAAU,CAC9B,OAAO,EACP,YAAY,EACZ,UAAU,GAAG,OAAO,EACpB,UAAU,GAAG,UAAU,EACvB,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,EAC/B,SAAS,GAAG,OAAO,EACnB,WAAW,GAAG,OAAO,CACrB,YACE,sBAAsB,CACpB,OAAO,EACP,YAAY,EACZ,UAAU,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,WAAW,CACZ;IAMH;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO;IAM7C;;;OAGG;IACH,WAAW,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,UAAU;IAEhD;;;OAGG;IACH,WAAW,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,UAAU;IAEhD;;;OAGG;IACH,UAAU,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,SAAS;IAE9C;;;OAGG;IACH,UAAU,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS;IAMnD;;;;OAIG;IACH,aAAa,CAAC,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY;IAE1C;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,OAAO,EAAE;IAQ7C;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW;IAe1C;;;;OAIG;IACH,gBAAgB,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAM3D;;;OAGG;IACH,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;CAG5C"}