@plyaz/types 1.22.8 → 1.23.0

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

@@ -2,6 +2,7 @@
  * CRUD Operation Types
  * Type definitions for CRUD operations in @plyaz/core domain services
  */
+import type { TransactionOptions } from '../../db/Transaction';
 /**
  * Cache-specific options for CRUD operations
  */
@@ -15,6 +16,16 @@ export interface CrudCacheOptions {
     /** Custom cache key (will still be prefixed with cachePrefix) */
     customKey?: string;
 }
+/**
+ * Transaction-specific options for CRUD operations
+ */
+export interface CrudTransactionOptions extends TransactionOptions {
+    /**
+     * Enable transaction for bulk operations (default: false for backwards compatibility)
+     * When true, all operations in bulkCreate/bulkDelete will be atomic
+     */
+    useTransaction?: boolean;
+}
 /**
  * Options for CRUD operations (create, getById, patch, delete, getAll)
  *
@@ -24,4 +35,6 @@ export interface CrudCacheOptions {
 export interface CrudOperationOptions {
     /** Cache-related options */
     cache?: CrudCacheOptions;
+    /** Transaction-related options (for bulk operations) */
+    transaction?: CrudTransactionOptions;
 }

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

@@ -3,4 +3,4 @@
  * Type definitions for @plyaz/core domain services
  */
 export type { CoreBaseDomainServiceInterface, CoreEventSubscribable, CoreProviderSubscribable, CoreValidationResult, CoreValidatorConfig, CoreBaseValidatorInstance, CoreBaseMapperInstance, CoreBaseDomainServiceConfig, CoreBaseBackendServiceConfig, CoreMapperClass, CoreValidatorClass, CoreBaseServiceConfig, CoreInjectedServices, } from './types';
-export type { CrudCacheOptions, CrudOperationOptions, } from './crud';
+export type { CrudCacheOptions, CrudTransactionOptions, CrudOperationOptions, } from './crud';

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

@@ -106,14 +106,33 @@ export type CoreValidatorClass<T extends CoreBaseValidatorInstance = CoreBaseVal
 /**
  * Injected services/dependencies for domain services.
  * These are created/managed by ServiceRegistry and injected into services.
+ *
+ * @typeParam TCache - Cache manager type (defaults to unknown for flexibility)
+ * @typeParam TDb - Database service type (defaults to unknown for flexibility)
+ * @typeParam TApi - API client type (defaults to unknown for flexibility)
+ * @typeParam TStores - Store types map (defaults to unknown)
+ *
+ * @example
+ * ```typescript
+ * // With specific types
+ * interface MyInjectedServices extends CoreInjectedServices<
+ *   CacheManager,
+ *   DatabaseServiceInterface,
+ *   ApiClient,
+ *   { users: UserStoreSlice }
+ * > {}
+ *
+ * // With defaults (unknown types)
+ * interface BasicInjectedServices extends CoreInjectedServices {}
+ * ```
  */
-export interface CoreInjectedServices<TStores = unknown> {
+export interface CoreInjectedServices<TCache = unknown, TDb = unknown, TApi = unknown, TStores = unknown> {
     /** Cache manager instance */
-    cache?: unknown;
+    cache?: TCache;
     /** Database service instance */
-    db?: unknown;
-    /** API client instance */
-    api?: unknown;
+    db?: TDb;
+    /** API client instance (supports multiple API clients via generics) */
+    api?: TApi;
     /**
      * Store instances (from root store) keyed by store key.
      * Type-safe: each key maps to its specific slice type.
@@ -161,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/events/payloads.d.ts

@@ -13,7 +13,7 @@
  * ```
  */
 import type { CORE_EVENTS } from './enums';
-import type { PackageErrorLike } from '../../errors';
+import type { PackageErrorLike, SerializedError } from '../../errors';
 /**
  * Core event structure
  *
@@ -206,9 +206,12 @@ export interface CoreSystemShutdownPayload {
  * Payload for system:error events
  */
 export interface CoreSystemErrorPayload {
-    error: unknown;
+    /** Array of serialized errors */
+    errors: SerializedError[];
+    /** Error context description */
     context?: string;
-    recoverable: boolean;
+    /** Whether the error is recoverable */
+    recoverable?: boolean;
 }
 /**
  * Payload for system:warning events

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.8",
+  "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.",