@plyaz/types 1.22.9 → 1.23.0

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

@@ -180,3 +180,188 @@ export interface CoreBaseBackendServiceConfig extends CoreBaseDomainServiceConfi
         defaultTtl?: number;
     };
 }
+/**
+ * Base interface for service type bundles.
+ * Define your concrete types by implementing this interface.
+ *
+ * This reduces the number of generic parameters from 13 to 5:
+ * - TConfig (service config)
+ * - TTypes (this bundle)
+ * - TRepository
+ * - TMapper
+ * - TValidator
+ *
+ * @example
+ * ```typescript
+ * // Define your service types bundle (no extends needed!)
+ * interface UserServiceTypes {
+ *   Entity: User;
+ *   ResponseDTO: UserResponseDTO;
+ *   CreateDTO: CreateUserDTO;
+ *   UpdateDTO: UpdateUserDTO;
+ *   PatchDTO: PatchUserDTO;
+ *   QueryDTO: QueryUserDTO;
+ *   DeleteOptions: { soft: boolean };
+ *   DatabaseRow: UserDatabaseRow;
+ *   StoreState: UserStoreItem;
+ * }
+ *
+ * // Use in service (5 generics instead of 13!)
+ * class UserService extends BaseBackendDomainServiceV2<
+ *   UserServiceConfig,
+ *   UserServiceTypes,
+ *   UserRepository,
+ *   UserMapper,
+ *   UserValidator
+ * > {}
+ * ```
+ */
+export interface BackendServiceTypesShape {
+    /** Domain entity type */
+    Entity: unknown;
+    /** API response DTO type */
+    ResponseDTO: unknown;
+    /** Create input DTO type (POST body) - must be Record<string, unknown> */
+    CreateDTO: Record<string, unknown>;
+    /** Update input DTO type (PUT body) - must be Record<string, unknown> */
+    UpdateDTO: Record<string, unknown>;
+    /** Patch input DTO type (PATCH body) */
+    PatchDTO: Partial<Record<string, unknown>>;
+    /** Query params DTO type */
+    QueryDTO: Record<string, unknown>;
+    /** Delete options type */
+    DeleteOptions: unknown;
+    /** Database row type - must be Record<string, unknown> */
+    DatabaseRow: Record<string, unknown>;
+    /** Store state type (serializable) */
+    StoreState: unknown;
+}
+/**
+ * Frontend service types shape (without database-specific types)
+ */
+export interface FrontendServiceTypesShape {
+    /** Domain entity type */
+    Entity: unknown;
+    /** API response DTO type */
+    ResponseDTO: unknown;
+    /** Create input DTO type */
+    CreateDTO: unknown;
+    /** Update input DTO type */
+    UpdateDTO: unknown;
+    /** Patch input DTO type */
+    PatchDTO: unknown;
+    /** Query params DTO type */
+    QueryDTO: unknown;
+    /** Store state type */
+    StoreState: unknown;
+}
+/**
+ * Helper to create a backend service types bundle with defaults.
+ * Use this when you want type inference with sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * type UserTypes = DefineBackendServiceTypes<{
+ *   Entity: User;
+ *   ResponseDTO: UserResponseDTO;
+ *   CreateDTO: CreateUserDTO;
+ *   // UpdateDTO defaults to CreateDTO
+ *   // PatchDTO defaults to Partial<CreateDTO>
+ *   QueryDTO: QueryUserDTO;
+ *   DatabaseRow: UserDatabaseRow;
+ * }>;
+ * ```
+ */
+export type DefineBackendServiceTypes<T extends Partial<BackendServiceTypesShape> & {
+    Entity: unknown;
+    CreateDTO: Record<string, unknown>;
+}> = {
+    Entity: T['Entity'];
+    ResponseDTO: T extends {
+        ResponseDTO: infer R;
+    } ? R : T['Entity'];
+    CreateDTO: T['CreateDTO'];
+    UpdateDTO: T extends {
+        UpdateDTO: infer U;
+    } ? U : T['CreateDTO'];
+    PatchDTO: T extends {
+        PatchDTO: infer P;
+    } ? P : Partial<T['CreateDTO']>;
+    QueryDTO: T extends {
+        QueryDTO: infer Q;
+    } ? Q : Record<string, unknown>;
+    DeleteOptions: T extends {
+        DeleteOptions: infer D;
+    } ? D : {
+        soft: boolean;
+    };
+    DatabaseRow: T extends {
+        DatabaseRow: infer DB;
+    } ? DB : T['CreateDTO'] & {
+        id: string;
+    };
+    StoreState: T extends {
+        StoreState: infer S;
+    } ? S : T['Entity'];
+};
+/**
+ * Helper to create a frontend service types bundle with defaults.
+ */
+export type DefineFrontendServiceTypes<T extends Partial<FrontendServiceTypesShape> & {
+    Entity: unknown;
+}> = {
+    Entity: T['Entity'];
+    ResponseDTO: T extends {
+        ResponseDTO: infer R;
+    } ? R : T['Entity'];
+    CreateDTO: T extends {
+        CreateDTO: infer C;
+    } ? C : Record<string, unknown>;
+    UpdateDTO: T extends {
+        UpdateDTO: infer U;
+    } ? U : T extends {
+        CreateDTO: infer C;
+    } ? C : Record<string, unknown>;
+    PatchDTO: T extends {
+        PatchDTO: infer P;
+    } ? P : Partial<T extends {
+        CreateDTO: infer C;
+    } ? C : Record<string, unknown>>;
+    QueryDTO: T extends {
+        QueryDTO: infer Q;
+    } ? Q : Record<string, unknown>;
+    StoreState: T extends {
+        StoreState: infer S;
+    } ? S : T['Entity'];
+};
+/**
+ * Type-safe extraction helpers for service type bundles.
+ * These work with any object that has the expected shape.
+ */
+export type ExtractEntity<T extends {
+    Entity: unknown;
+}> = T['Entity'];
+export type ExtractResponseDTO<T extends {
+    ResponseDTO: unknown;
+}> = T['ResponseDTO'];
+export type ExtractCreateDTO<T extends {
+    CreateDTO: unknown;
+}> = T['CreateDTO'];
+export type ExtractUpdateDTO<T extends {
+    UpdateDTO: unknown;
+}> = T['UpdateDTO'];
+export type ExtractPatchDTO<T extends {
+    PatchDTO: unknown;
+}> = T['PatchDTO'];
+export type ExtractQueryDTO<T extends {
+    QueryDTO: unknown;
+}> = T['QueryDTO'];
+export type ExtractDeleteOptions<T extends {
+    DeleteOptions: unknown;
+}> = T['DeleteOptions'];
+export type ExtractDatabaseRow<T extends {
+    DatabaseRow: unknown;
+}> = T['DatabaseRow'];
+export type ExtractStoreState<T extends {
+    StoreState: unknown;
+}> = T['StoreState'];

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

@@ -2,5 +2,5 @@
  * Core Frontend Types
  * Type definitions for @plyaz/core frontend services
  */
-export type { CoreBaseFrontendStore, CoreBaseFrontendServiceConfig, CoreBaseFrontendServiceInterface, CoreStoreHandlers, CoreFetcherFunction, CoreServiceFetchers, CorePlyazApiConfig, FrontendFeatureFlagProvider, CorePlyazFeatureFlagConfig, CorePlyazStoreConfig, CorePlyazConfig, CoreFeatureFlagServiceLike, CoreFeatureFlagFetcherOptions, CoreFeatureFlagStoreInitConfig, CoreBaseFrontendServiceConstructorConfig, CoreInitializationErrorProps, CoreInitializationLoadingProps, CorePlyazServices, CorePlyazContextValue, CorePlyazProviderProps, } from './types';
+export type { CoreBaseFrontendStore, CoreBaseFrontendServiceConfig, CoreBaseFrontendServiceInterface, CoreStoreHandlers, CoreOptimisticUpdateConfig, OptimisticConflictResolution, CoreFetcherFunction, CoreServiceFetchers, CorePlyazApiConfig, FrontendFeatureFlagProvider, CorePlyazFeatureFlagConfig, CorePlyazStoreConfig, CorePlyazConfig, CoreFeatureFlagServiceLike, CoreFeatureFlagFetcherOptions, CoreFeatureFlagStoreInitConfig, CoreBaseFrontendServiceConstructorConfig, CoreInitializationErrorProps, CoreInitializationLoadingProps, CorePlyazServices, CorePlyazContextValue, CorePlyazProviderProps, } from './types';
 export type { CoreFrontendFeatureFlagEventType, CoreFeatureFlagStore, CoreFeatureFlagServiceConfig, CoreFeatureFlagServiceInitConfig, CoreFeatureFlagServiceInterface, } from './featureFlags';

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

@@ -638,6 +638,68 @@ export interface CoreStoreHandlers<TData = Record<string, unknown>, TStore exten
      */
     removeData?: (store: TStore, id: string) => void;
 }
+/**
+ * Conflict resolution strategy for optimistic updates
+ */
+export type OptimisticConflictResolution = 'server-wins' | 'client-wins' | 'merge' | 'manual';
+/**
+ * Optimistic update configuration
+ *
+ * When enabled, store updates happen immediately before API call completes.
+ * If the API call fails, changes are rolled back automatically.
+ *
+ * @example
+ * ```typescript
+ * optimisticUpdates: {
+ *   enabled: true,
+ *   rollbackOnError: true,
+ *   conflictResolution: 'server-wins',
+ * }
+ * ```
+ */
+export interface CoreOptimisticUpdateConfig {
+    /**
+     * Enable optimistic updates for CRUD operations.
+     * When true, store is updated before API response.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Automatically rollback on API error.
+     * When true, reverts store to previous state if API fails.
+     * @default true
+     */
+    rollbackOnError?: boolean;
+    /**
+     * How to resolve conflicts when server response differs from optimistic state.
+     * - 'server-wins': Always use server response (default, safest)
+     * - 'client-wins': Keep client changes, ignore server differences
+     * - 'merge': Deep merge server and client data
+     * - 'manual': Call onConflict handler for resolution
+     * @default 'server-wins'
+     */
+    conflictResolution?: OptimisticConflictResolution;
+    /**
+     * Delay before applying optimistic update (ms).
+     * Useful for debouncing rapid updates.
+     * @default 0
+     */
+    debounceMs?: number;
+    /**
+     * Operations to enable optimistic updates for.
+     * @default ['create', 'update', 'delete']
+     */
+    operations?: ('create' | 'update' | 'delete')[];
+    /**
+     * Called when conflict detected (only when conflictResolution is 'manual').
+     * Return the resolved data to use.
+     */
+    onConflict?: <T>(optimistic: T, server: T) => T;
+    /**
+     * Called when rollback occurs due to error.
+     */
+    onRollback?: (operation: string, error: Error, previousState: unknown) => void;
+}
 /**
  * Configuration for frontend domain services
  */
@@ -684,6 +746,24 @@ export interface CoreBaseFrontendServiceConfig<TData = Record<string, unknown>,
      * ```
      */
     storeHandlers?: CoreStoreHandlers<TData, TStore>;
+    /**
+     * Optimistic update configuration.
+     *
+     * When enabled, store updates happen immediately before API completes.
+     * If API fails, changes are automatically rolled back.
+     *
+     * @see {@link CoreOptimisticUpdateConfig} for options
+     *
+     * @example
+     * ```typescript
+     * optimisticUpdates: {
+     *   enabled: true,
+     *   rollbackOnError: true,
+     *   conflictResolution: 'server-wins',
+     * }
+     * ```
+     */
+    optimisticUpdates?: CoreOptimisticUpdateConfig;
 }
 /**
  * Base interface for frontend domain services with store integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.22.9",
+  "version": "1.23.0",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",