reslib 1.0.0

package/build/resources/types/index.d.ts

@@ -0,0 +1,4138 @@
+import { AuthPerm } from '../../auth/types';
+import { InputFormatterOptions } from '../../inputFormatter/types';
+import { Dictionary, UppercaseFirst } from '../../types/dictionary';
+import { MongoQuery, ResourceQueryOrderBy } from './filters';
+export * from './filters';
+export interface FieldBase<TFieldType extends FieldType = FieldType, TValueType = any> extends Partial<ResourceActionTupleObject<ResourceName>>, Omit<InputFormatterOptions<TFieldType, TValueType>, 'value' | 'type'> {
+    /**
+     * The type of the field.
+     *
+     * @description
+     * This property specifies the type of the field, such as "text", "number", or "date".
+     *
+     * @default "text"
+     *
+     * @example
+     * ```typescript
+     * const textField: FieldBase = {
+     *   type: 'text'
+     * };
+     * ```
+     */
+    type: TFieldType;
+    /**
+     * The name of the field.
+     *
+     * @description
+     * This property specifies the unique name or identifier for the field.
+     *
+     * @example
+     * ```typescript
+     * const textField: FieldBase = {
+     *   name: 'textField'
+     * };
+     * ```
+     */
+    name?: string;
+    /**
+     * The name of the field in the database table.
+     *
+     * @description
+     * This property specifies the name of the field as it appears in the database table.
+     *
+     * @example
+     * ```typescript
+     * const textField: FieldBase = {
+     *   databaseName: 'text_field'
+     * };
+     * ```
+     */
+    databaseName?: string;
+    /**
+     * The name of the field's table or collection in the database.
+     *
+     * @description
+     * This property specifies the name of the table or collection that contains the field in the database.
+     *
+     * @example
+     * ```typescript
+     * const textField: FieldBase = {
+     *   databaseTableName: 'text_fields'
+     * };
+     * ```
+     */
+    databaseTableName?: string;
+    /***
+     * weatherr the field is a primary key or not
+     */
+    primaryKey?: boolean;
+    /**
+     * weatherr the field is rendable or not
+     * It is used to determine if the field should be rendered or not.
+     */
+    rendable?: boolean;
+    /***
+     * weatherr the field is readonly or not
+     */
+    readOnly?: boolean;
+    /**
+     * weatherr the field is disabled or not
+     */
+    disabled?: boolean;
+    /***
+     * weatherr the field is unique for the resource or not
+     */
+    unique?: boolean;
+    /**
+     * weatherr the field is required or not
+     */
+    required?: boolean;
+    /***
+     * the min length of the field
+     */
+    minLength?: number;
+    /**
+     * the max length of the field
+     */
+    maxLength?: number;
+    /**
+     * the length of the field
+     */
+    length?: number;
+    /***
+     * whether the field is visible or not
+     */
+    visible?: boolean;
+    /***
+     * The permission associated with the field. This permission is used to determine if the field will be rendered or not.
+     */
+    perm?: AuthPerm;
+    /**
+     * The default value of the field.
+     */
+    defaultValue?: TValueType;
+}
+/**
+ * ## FieldMap Interface
+ *
+ * A global interface for defining field mappings in the resource system.
+ * This interface serves as a central registry for all available field types
+ * and their configurations, enabling type-safe field definitions across the application.
+ *
+ * ### Purpose
+ * The `FieldMap` interface is designed for **module augmentation**, allowing developers
+ * to extend it with custom field definitions. Each key represents a field type (e.g., "text", "number"),
+ * and each value must extend the `FieldBase` interface, ensuring consistent structure
+ * and type safety for all field configurations.
+ *
+ * ### How It Works
+ * - **Empty by Design**: The interface is intentionally empty in the core library.
+ * - **Module Augmentation**: Developers extend it via `declare module` statements.
+ * - **Type Safety**: The `Field<T>` type uses `FieldMap[T]` to enforce that field
+ *   configurations match their declared types.
+ * - **Extensibility**: New field types can be added without modifying the core library.
+ *
+ * ### Template Parameters
+ * This interface doesn't use generic parameters itself, but the values must conform to `FieldBase<TFieldType, ValueType>`.
+ *
+ * ### Examples
+ *
+ * #### Basic Module Augmentation
+ * ```typescript
+ * // In your application's types file (e.g., types.ts or global.d.ts)
+ * import "reslib/resources";
+ *
+ * declare module "reslib/resources/resources" {
+ *   interface FieldMap {
+ *     // Define a text field type
+ *     text: FieldBase<"text", string>;
+ *
+ *     // Define a number field type
+ *     number: FieldBase<"number", number>;
+ *
+ *     // Define an email field type
+ *     email: FieldBase<"email", string>;
+ *   }
+ * }
+ * ```
+ *
+ * #### Advanced FieldMeta Configuration
+ * ```typescript
+ * declare module "reslib/resources/resources" {
+ *   interface FieldMap {
+ *     // Text field with validation
+ *     text: FieldBase<"text", string> & {
+ *       minLength?: number;
+ *       maxLength?: number;
+ *       pattern?: RegExp;
+ *     };
+ *
+ *     // Number field with range constraints
+ *     number: FieldBase<"number", number> & {
+ *       min?: number;
+ *       max?: number;
+ *       step?: number;
+ *     };
+ *
+ *     // Select field with predefined options
+ *     select: FieldBase<"select", string> & {
+ *       options: Array<{ label: string; value: string }>;
+ *       multiple?: boolean;
+ *     };
+ *
+ *     // Date field with format options
+ *     date: FieldBase<"date", Date> & {
+ *       format?: string;
+ *       minDate?: Date;
+ *       maxDate?: Date;
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * #### Using Defined Fields
+ * ```typescript
+ * // After augmentation, you can create type-safe fields
+ * const userFields: Fields = {
+ *   username: {
+ *     type: "text",        // ✓ TypeScript knows this is valid
+ *     name: "username",
+ *     required: true,
+ *     minLength: 3,        // ✓ Additional properties available
+ *     maxLength: 50,
+ *     forCreate: { required: true },
+ *     forUpdate: { required: false }
+ *   },
+ *   age: {
+ *     type: "number",      // ✓ TypeScript knows this is valid
+ *     name: "age",
+ *     min: 0,              // ✓ Range constraints available
+ *     max: 150,
+ *     forFilter: { allowRange: true }
+ *   },
+ *   email: {
+ *     type: "email",       // ✓ TypeScript knows this is valid
+ *     name: "email",
+ *     required: true,
+ *     forCreate: { required: true }
+ *   }
+ * };
+ *
+ * // TypeScript will catch invalid field types:
+ * // const invalidField: Field = { type: "invalid" }; // ✗ Error: "invalid" not in FieldMap
+ * ```
+ *
+ * #### Conditional FieldMeta Extensions
+ * ```typescript
+ * declare module "reslib/resources/resources" {
+ *   interface FieldMap {
+ *     // Conditional field that changes behavior based on context
+ *     conditional: FieldBase<"conditional", any> & {
+ *       condition: (context: any) => boolean;
+ *       trueField: keyof FieldMap;
+ *       falseField: keyof FieldMap;
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * ### Best Practices
+ * - **Consistent Naming**: Use lowercase strings for field type keys (e.g., "text", "number").
+ * - **Extensive Properties**: Add as many type-specific properties as needed for your use case.
+ * - **Documentation**: Document custom field types clearly for team members.
+ * - **Versioning**: Consider the impact on existing field definitions when adding new properties.
+ * - **Validation**: Use TypeScript's type system to enforce field constraints at compile time.
+ *
+ * ### Integration with Other Types
+ * - **Field<T>**: Uses `FieldMap[T]` to create type-safe field configurations.
+ * - **FieldType**: Derives from `keyof FieldMap` to constrain valid field types.
+ * - **FieldBase**: Provides the base structure that all field definitions must extend.
+ *
+ * ### Migration Notes
+ * If you're upgrading from a version where field types were defined differently,
+ * update your module augmentations to use this new structure for better type safety.
+ *
+ * @interface FieldMap
+ * @public
+ *
+ * @see {@link FieldBase} - The base interface that field definitions must extend
+ * @see {@link Field} - How field configurations are created from this map
+ * @see {@link FieldType} - The union type of all defined field types
+ * @example
+ * ```typescript
+ * // Complete example of extending FieldMap
+ * declare module "reslib/resources/resources" {
+ *   interface FieldMap {
+ *     text: FieldBase<"text", string> & {
+ *       minLength?: number;
+ *       maxLength?: number;
+ *       placeholder?: string;
+ *     };
+ *
+ *     number: FieldBase<"number", number> & {
+ *       min?: number;
+ *       max?: number;
+ *       step?: number;
+ *     };
+ *
+ *     boolean: FieldBase<"boolean", boolean>;
+ *
+ *     date: FieldBase<"date", Date> & {
+ *       format?: string;
+ *     };
+ *
+ *     select: FieldBase<"select", string> & {
+ *       options: Array<{ label: string; value: any }>;
+ *       multiple?: boolean;
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface FieldMap {
+}
+/**
+ * ## FieldActionsMap Interface
+ *
+ * A global interface defining the action contexts available for field configurations.
+ * This interface serves as a central registry for all possible field action types
+ * that can have different validation rules, requirements, or behaviors.
+ *
+ * ### Purpose
+ * The `FieldActionsMap` interface defines the different contexts in which fields
+ * can be used within the resource system. Each key represents an action context
+ * (e.g., "create", "update", "filter"), and the corresponding string value is used
+ * for type-level operations and transformations.
+ *
+ * ### How It Works
+ * - **Action Contexts**: Defines the different operations where field behavior might differ
+ * - **Type Generation**: Used by `Field<T>` to generate action-specific field overrides
+ *   like `forCreate`, `forUpdate`, `forCreateOrUpdate`, and `forFilter`
+ * - **Module Augmentation**: Can be extended via `declare module` for custom action contexts
+ * - **String Values**: The string values are primarily used for TypeScript type manipulation
+ *
+ * ### Default Action Contexts
+ *
+ * - **create**: FieldMeta configuration when creating new resource instances
+ * - **update**: FieldMeta configuration when updating existing resource instances
+ * - **createOrUpdate**: FieldMeta configuration for operations that can create or update
+ * - **filter**: FieldMeta configuration for filtering/searching resource instances
+ *
+ * ### Template Parameters
+ * This interface doesn't use generic parameters itself, but serves as a foundation
+ * for generating action-specific field configurations.
+ *
+ * ### Examples
+ *
+ * #### Basic Usage in FieldMeta Definitions
+ * ```typescript
+ * // Fields can have different configurations for different actions
+ * const userFields: Fields = {
+ *   password: {
+ *     type: "text",
+ *     required: true,
+ *     minLength: 8,
+ *     // Different requirements for create vs update
+ *     forCreate: { required: true },  // Password required when creating
+ *     forUpdate: { required: false }  // Password optional when updating
+ *   },
+ *   email: {
+ *     type: "email",
+ *     required: true,
+ *     unique: true,
+ *     // Email validation differs by context
+ *     forCreate: { required: true, unique: true },
+ *     forUpdate: { required: true, unique: true },
+ *     forFilter: { required: false } // Email optional for filtering
+ *   }
+ * };
+ * ```
+ *
+ * #### Module Augmentation for Custom Actions
+ * ```typescript
+ * // In your application's types file
+ * import "reslib/resources/resources";
+ *
+ * declare module "reslib/resources/resources" {
+ *   interface FieldActionsMap {
+ *     // Add custom action contexts
+ *     import: string;      // For bulk import operations
+ *     export: string;      // For data export configurations
+ *     validate: string;    // For validation-only contexts
+ *     preview: string;     // For preview/display contexts
+ *   }
+ * }
+ *
+ * // Now you can use these in field definitions
+ * const productFields: Fields = {
+ *   sku: {
+ *     type: "text",
+ *     required: true,
+ *     forCreate: { required: true },
+ *     forUpdate: { required: true },
+ *     forImport: { required: true, pattern: "^[A-Z0-9]+$" }, // Custom validation for imports
+ *     forExport: { required: false } // SKU optional in exports
+ *   }
+ * };
+ * ```
+ *
+ * #### Advanced FieldMeta Behavior Overrides
+ * ```typescript
+ * declare module "reslib/resources/resources" {
+ *   interface FieldActionsMap {
+ *     bulkUpdate: string;
+ *     softDelete: string;
+ *     archive: string;
+ *   }
+ * }
+ *
+ * const documentFields: Fields = {
+ *   status: {
+ *     type: "select",
+ *     options: ["draft", "published", "archived"],
+ *     required: true,
+ *     forCreate: { required: true, defaultValue: "draft" },
+ *     forUpdate: { required: true },
+ *     forBulkUpdate: { required: false }, // Optional in bulk operations
+ *     forSoftDelete: { readOnly: true },  // Can't change status when soft deleting
+ *     forArchive: { required: true, allowedValues: ["archived"] } // Only allow archive status
+ *   },
+ *   deletedAt: {
+ *     type: "date",
+ *     readOnly: true,
+ *     forSoftDelete: { required: true }, // Must set deletion timestamp
+ *     forArchive: { required: false }    // Optional for archiving
+ *   }
+ * };
+ * ```
+ *
+ * #### Conditional FieldMeta Requirements
+ * ```typescript
+ * const orderFields: Fields = {
+ *   paymentMethod: {
+ *     type: "select",
+ *     options: ["credit_card", "paypal", "bank_transfer"],
+ *     forCreate: { required: true },
+ *     forUpdate: { required: false }, // Can't change payment method after creation
+ *     forFilter: { required: false }
+ *   },
+ *   creditCardNumber: {
+ *     type: "text",
+ *     pattern: "^\\d{16}$",
+ *     forCreate: {
+ *       required: true,
+ *       // Only required if payment method is credit card
+ *       conditionalRequired: (data) => data.paymentMethod === "credit_card"
+ *     },
+ *     forUpdate: { readOnly: true }, // Never updatable for security
+ *     forFilter: { required: false }
+ *   }
+ * };
+ * ```
+ *
+ * ### Best Practices
+ * - **Consistent Naming**: Use lowercase action names (e.g., "create", "update")
+ * - **Semantic Actions**: Choose action names that clearly describe their purpose
+ * - **Minimal Overrides**: Only override field properties when behavior genuinely differs
+ * - **Security Considerations**: Use action contexts to enforce security rules
+ *   (e.g., making fields read-only in certain contexts)
+ * - **Documentation**: Document custom action contexts for team members
+ *
+ * ### Integration with Other Types
+ * - **Field<T>**: Uses `FieldActionsMap` to generate action-specific properties
+ * - **FieldMap**: Provides the base field configurations that can be overridden
+ * - **UppercaseFirst**: Used to transform action names (e.g., "create" → "Create" → "forCreate")
+ *
+ * ### Migration Notes
+ * When adding new action contexts, ensure that existing field definitions are
+ * compatible. Consider providing default behaviors for new actions to maintain
+ * backward compatibility.
+ *
+ * @interface FieldActionsMap
+ * @public
+ *
+ * @see {@link Field} - How action contexts are used in field definitions
+ * @see {@link FieldMap} - The base field configurations that can be overridden
+ * @see {@link UppercaseFirst} - Utility for transforming action names
+ * @example
+ * ```typescript
+ * // Complete example of extending FieldActionsMap
+ * declare module "reslib/resources/resources" {
+ *   interface FieldActionsMap {
+ *     // Standard CRUD operations
+ *     create: string;
+ *     update: string;
+ *     createOrUpdate: string;
+ *     filter: string;
+ *
+ *     // Custom business logic actions
+ *     approve: string;      // For approval workflows
+ *     reject: string;       // For rejection workflows
+ *     publish: string;      // For content publishing
+ *     archive: string;      // For archiving operations
+ *
+ *     // Data operations
+ *     import: string;       // For bulk import
+ *     export: string;       // For data export
+ *     migrate: string;      // For data migration
+ *
+ *     // Administrative actions
+ *     adminUpdate: string;  // For admin-only updates
+ *     systemUpdate: string; // For system-generated updates
+ *   }
+ * }
+ *
+ * // Usage in field definitions
+ * const contentFields: Fields = {
+ *   publishedAt: {
+ *     type: "date",
+ *     readOnly: true,
+ *     forCreate: { required: false },
+ *     forPublish: { required: true },    // Must set when publishing
+ *     forUpdate: { required: false },
+ *     forAdminUpdate: { required: false } // Admins can modify
+ *   },
+ *   approvalStatus: {
+ *     type: "select",
+ *     options: ["pending", "approved", "rejected"],
+ *     defaultValue: "pending",
+ *     forCreate: { required: false },
+ *     forApprove: { required: true, allowedValues: ["approved"] },
+ *     forReject: { required: true, allowedValues: ["rejected"] },
+ *     forUpdate: { readOnly: true } // Status changes through specific actions
+ *   }
+ * };
+ * ```
+ */
+export interface FieldActionsMap {
+    create: string;
+    update: string;
+    createOrUpdate: string;
+    filter: string;
+}
+/**
+ * ## Field Type
+ *
+ * The core type representing a field configuration in the resource system.
+ * This conditional type combines base field properties with action-specific overrides,
+ * enabling flexible and type-safe field definitions across different operations.
+ *
+ * ### Purpose
+ * The `Field` type serves as the primary interface for defining fields in resource schemas.
+ * It provides a structured way to specify field behavior, validation rules, and operation-specific
+ * customizations, ensuring type safety and consistency throughout the application.
+ *
+ * ### How It Works
+ * This type uses TypeScript's conditional types and mapped types to dynamically construct
+ * field configurations based on the field type and available actions:
+ *
+ * 1. **Base Configuration**: Inherits all properties from the specific field type in `FieldMap[T]`
+ * 2. **Action Overrides**: Adds optional properties for each action in `FieldActionsMap`
+ * 3. **Type Safety**: Ensures only valid field types and action contexts are used
+ * 4. **Extensibility**: Supports module augmentation for custom field types and actions
+ *
+ * ### Template Parameters
+ * - **T**: The field type (extends `FieldType`, which is `keyof FieldMap`). Defaults to `FieldType`.
+ *
+ * ### Type Construction
+ * ```typescript
+ * Field<T> = FieldMap[T] extends FieldBase
+ *   ? FieldMap[T] & {
+ *       [key in keyof FieldActionsMap as `for${UppercaseFirst<key>}`]?: Partial<FieldMap[keyof FieldMap]>
+ *     }
+ *   : never
+ * ```
+ *
+ * This creates a type that includes:
+ * - All base properties from `FieldMap[T]` (e.g., `type`, `name`, `required`, field-specific properties)
+ * - Optional action-specific overrides like `forCreate`, `forUpdate`, `forFilter`, etc.
+ *
+ * ### Examples
+ *
+ * #### Basic Field Definition
+ * ```typescript
+ * // Define a text field with basic properties
+ * const usernameField: Field<"text"> = {
+ *   type: "text",
+ *   name: "username",
+ *   required: true,
+ *   minLength: 3,
+ *   maxLength: 50,
+ *   placeholder: "Enter username"
+ * };
+ * ```
+ *
+ * #### Field with Action-Specific Overrides
+ * ```typescript
+ * // Field that behaves differently for different actions
+ * const passwordField: Field<"text"> = {
+ *   type: "text",
+ *   name: "password",
+ *   // Base configuration
+ *   minLength: 8,
+ *   pattern: "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).+$",
+ *
+ *   // Action-specific overrides
+ *   forCreate: {
+ *     required: true,        // Password required when creating
+ *     minLength: 8          // Minimum length for creation
+ *   },
+ *   forUpdate: {
+ *     required: false,       // Password optional when updating
+ *     minLength: 0           // No minimum when updating (keep existing)
+ *   },
+ *   forFilter: {
+ *     required: false,       // Not used in filtering
+ *     minLength: 0
+ *   }
+ * };
+ * ```
+ *
+ * #### Complex Field with Multiple Overrides
+ * ```typescript
+ * const statusField: Field<"select"> = {
+ *   type: "select",
+ *   name: "status",
+ *   required: true,
+ *   options: ["draft", "published", "archived"],
+ *   defaultValue: "draft",
+ *
+ *   // Different validation rules per action
+ *   forCreate: {
+ *     required: false,       // Optional during creation
+ *     defaultValue: "draft"  // Default to draft
+ *   },
+ *   forUpdate: {
+ *     required: true,        // Required during updates
+ *     allowedValues: ["published", "archived"] // Can't go back to draft
+ *   },
+ *   forFilter: {
+ *     required: false,       // Optional in filters
+ *     multiple: true         // Allow multiple values in filters
+ *   }
+ * };
+ * ```
+ *
+ * #### Field Collection Usage
+ * ```typescript
+ * // Using fields in a resource definition
+ * const userFields: Fields = {
+ *   id: {
+ *     type: "uuid",
+ *     name: "id",
+ *     primaryKey: true,
+ *     readOnly: true
+ *   },
+ *   username: {
+ *     type: "text",
+ *     name: "username",
+ *     required: true,
+ *     minLength: 3,
+ *     maxLength: 50,
+ *     forCreate: { required: true },
+ *     forUpdate: { required: true }
+ *   },
+ *   email: {
+ *     type: "email",
+ *     name: "email",
+ *     required: true,
+ *     unique: true,
+ *     forCreate: { required: true, unique: true },
+ *     forUpdate: { required: true, unique: true }
+ *   },
+ *   role: {
+ *     type: "select",
+ *     name: "role",
+ *     options: ["admin", "user", "moderator"],
+ *     defaultValue: "user",
+ *     forCreate: { required: false },
+ *     forUpdate: { required: true, allowedValues: ["admin", "user"] }
+ *   }
+ * };
+ * ```
+ *
+ * #### Type-Safe Field Access
+ * ```typescript
+ * // TypeScript ensures type safety
+ * function processField<T extends FieldType>(field: Field<T>) {
+ *   // field.type is guaranteed to be T
+ *   // field.name is always available
+ *   // Action overrides are optional and type-safe
+ *
+ *   if (field.forCreate) {
+ *     console.log("Create-specific config:", field.forCreate);
+ *   }
+ *
+ *   if (field.forUpdate) {
+ *     console.log("Update-specific config:", field.forUpdate);
+ *   }
+ * }
+ * ```
+ *
+ * #### Advanced Usage with Custom Field Types
+ * ```typescript
+ * // After extending FieldMap with custom types
+ * declare module "reslib/resources/resources" {
+ *   interface FieldMap {
+ *     richText: FieldBase<"richText", string> & {
+ *       toolbar: string[];
+ *       maxLength: number;
+ *       allowedFormats: string[];
+ *     };
+ *     dateRange: FieldBase<"dateRange", { start: Date; end: Date }> & {
+ *       minDate?: Date;
+ *       maxDate?: Date;
+ *       format: string;
+ *     };
+ *   }
+ * }
+ *
+ * // Now you can use these custom types
+ * const contentField: Field<"richText"> = {
+ *   type: "richText",
+ *   name: "content",
+ *   toolbar: ["bold", "italic", "link"],
+ *   maxLength: 10000,
+ *   allowedFormats: ["html", "markdown"],
+ *   forCreate: { required: true },
+ *   forUpdate: { required: false }
+ * };
+ *
+ * const dateRangeField: Field<"dateRange"> = {
+ *   type: "dateRange",
+ *   name: "eventDates",
+ *   format: "YYYY-MM-DD",
+ *   minDate: new Date(),
+ *   forFilter: { required: false }
+ * };
+ * ```
+ *
+ * ### Action-Specific Properties
+ * The `Field` type automatically generates properties for each action defined in `FieldActionsMap`:
+ *
+ * - **`forCreate`**: Configuration when creating new resource instances
+ * - **`forUpdate`**: Configuration when updating existing resource instances
+ * - **`forCreateOrUpdate`**: Configuration for operations that can create or update
+ * - **`forFilter`**: Configuration for filtering/searching resource instances
+ *
+ * Each action property is optional and can contain any subset of properties from any field type,
+ * allowing flexible customization of field behavior per operation.
+ *
+ * ### Best Practices
+ * - **Consistent Base Properties**: Define common properties (like `name`, `type`) at the base level
+ * - **Minimal Overrides**: Only specify action-specific properties when behavior genuinely differs
+ * - **Type Safety**: Leverage TypeScript's inference for field types and action properties
+ * - **Documentation**: Document custom field types and their action-specific behaviors
+ * - **Validation**: Use action overrides to enforce security rules and business logic
+ *
+ * ### Integration with Other Types
+ * - **`FieldMap`**: Provides the base field type definitions
+ * - **`FieldActionsMap`**: Defines available action contexts
+ * - **`Fields`**: Collection of fields for resource definitions
+ * - **`FieldBase`**: Common base properties for all field types
+ * - **`FieldType`**: Union of all valid field type keys
+ *
+ * ### Migration Notes
+ * When upgrading from simpler field definitions, gradually add action-specific overrides
+ * to maintain backward compatibility. The base properties remain available and functional
+ * even when action overrides are not specified.
+ *
+ * @type Field
+ * @template T - The field type (must be a key of FieldMap)
+ * @default FieldType
+ * @public
+ *
+ * @see {@link FieldMap} - The interface defining field type configurations
+ * @see {@link FieldActionsMap} - The interface defining action contexts
+ * @see {@link FieldBase} - The base properties shared by all field types
+ * @see {@link Fields} - How fields are collected into resource schemas
+ * @example
+ * ```typescript
+ * // Complete example of field definitions with action overrides
+ * import "reslib/resources/resources";
+ *
+ * declare module "reslib/resources/resources" {
+ *   interface FieldMap {
+ *     text: FieldBase<"text", string> & {
+ *       minLength?: number;
+ *       maxLength?: number;
+ *       pattern?: RegExp;
+ *       placeholder?: string;
+ *     };
+ *     select: FieldBase<"select", string> & {
+ *       options: string[];
+ *       multiple?: boolean;
+ *       defaultValue?: string;
+ *     };
+ *     number: FieldBase<"number", number> & {
+ *       min?: number;
+ *       max?: number;
+ *       step?: number;
+ *     };
+ *   }
+ * }
+ *
+ * // Define a comprehensive user resource schema
+ * const userFields: Fields = {
+ *   username: {
+ *     type: "text",
+ *     name: "username",
+ *     required: true,
+ *     minLength: 3,
+ *     maxLength: 50,
+ *     pattern: /^[a-zA-Z0-9_]+$/,
+ *     forCreate: { required: true },
+ *     forUpdate: { required: true },
+ *     forFilter: { required: false }
+ *   } as Field<"text">,
+ *
+ *   email: {
+ *     type: "email",
+ *     name: "email",
+ *     required: true,
+ *     forCreate: { required: true },
+ *     forUpdate: { required: true },
+ *     forFilter: { required: false }
+ *   } as Field<"text">, // email extends text with validation
+ *
+ *   role: {
+ *     type: "select",
+ *     name: "role",
+ *     options: ["admin", "user", "moderator"],
+ *     defaultValue: "user",
+ *     forCreate: { required: false },
+ *     forUpdate: { required: true },
+ *     forFilter: { required: false, multiple: true }
+ *   } as Field<"select">,
+ *
+ *   age: {
+ *     type: "number",
+ *     name: "age",
+ *     min: 0,
+ *     max: 150,
+ *     forCreate: { required: false },
+ *     forUpdate: { required: false },
+ *     forFilter: { required: false, min: 18, max: 100 }
+ *   } as Field<"number">
+ * };
+ *
+ * // Type-safe usage
+ * function validateField(field: Field, action: keyof FieldActionsMap, value: any): boolean {
+ *   const actionConfig = field[`for${action.charAt(0).toUpperCase() + action.slice(1)}` as keyof Field];
+ *
+ *   if (actionConfig && 'required' in actionConfig) {
+ *     if (actionConfig.required && (value === undefined || value === null)) {
+ *       return false;
+ *     }
+ *   }
+ *
+ *   // Additional validation logic...
+ *   return true;
+ * }
+ * ```
+ */
+export type Field<T extends FieldType = FieldType> = FieldMap[T] extends FieldBase ? FieldMap[T] & {
+    [key in keyof FieldActionsMap as `for${UppercaseFirst<key>}`]?: Partial<FieldMap[keyof FieldMap]>;
+} : never;
+/**
+ * Type representing a collection of fields where each key is a string and each value is an Field.
+ * This type is used to define the structure of fields for a resource or form.
+ *
+ * This type provides a flexible way to define multiple fields with their configurations,
+ * validation rules, and action-specific overrides. It's commonly used when defining
+ * the schema for resources, forms, or data validation.
+ *
+ * @type Fields
+ *
+ * @example
+ * ```typescript
+ * // Basic field collection for a user resource
+ * const userFields: Fields = {
+ *   username: {
+ *     type: "text",
+ *     name: "username",
+ *     required: true,
+ *     minLength: 3,
+ *     maxLength: 50,
+ *     forCreate: { required: true },
+ *     forUpdate: { required: false }
+ *   },
+ *   email: {
+ *     type: "email",
+ *     name: "email",
+ *     required: true,
+ *     unique: true,
+ *     forCreate: { required: true },
+ *     forUpdate: { required: true }
+ *   },
+ *   age: {
+ *     type: "number",
+ *     name: "age",
+ *     required: false,
+ *     min: 0,
+ *     max: 150,
+ *     forFilter: { allowRange: true }
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Dynamic field collection based on user permissions
+ * function createFieldsForUser(userRole: string): Fields {
+ *   const baseFields: Fields = {
+ *     id: { type: "uuid", name: "id", primaryKey: true, readOnly: true },
+ *     createdAt: { type: "date", name: "createdAt", readOnly: true },
+ *     updatedAt: { type: "date", name: "updatedAt", readOnly: true }
+ *   };
+ *
+ *   if (userRole === 'admin') {
+ *     return {
+ *       ...baseFields,
+ *       adminNotes: {
+ *         type: "textarea",
+ *         name: "adminNotes",
+ *         required: false,
+ *         maxLength: 1000
+ *       },
+ *       isActive: {
+ *         type: "boolean",
+ *         name: "isActive",
+ *         required: true,
+ *         defaultValue: true
+ *       }
+ *     };
+ *   }
+ *
+ *   return baseFields;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Form validation using field collection
+ * function validateFormData(fields: Fields, data: Record<string, any>): ValidationResult {
+ *   const errors: string[] = [];
+ *
+ *   for (const [fieldName, fieldConfig] of Object.entries(fields)) {
+ *     const value = data[fieldName];
+ *
+ *     // Check required fields
+ *     if (fieldConfig.required && (value === undefined || value === null || value === '')) {
+ *       errors.push(`${fieldConfig.name || fieldName} is required`);
+ *     }
+ *
+ *     // Check string length constraints
+ *     if (typeof value === 'string') {
+ *       if (fieldConfig.minLength && value.length < fieldConfig.minLength) {
+ *         errors.push(`${fieldName} must be at least ${fieldConfig.minLength} characters`);
+ *       }
+ *       if (fieldConfig.maxLength && value.length > fieldConfig.maxLength) {
+ *         errors.push(`${fieldName} must be at most ${fieldConfig.maxLength} characters`);
+ *       }
+ *     }
+ *   }
+ *
+ *   return { isValid: errors.length === 0, errors };
+ * }
+ * ```
+ */
+export type Fields = Record<string, Field>;
+/**
+ * Type representing the union of all possible field types defined in FieldMap.
+ * This type is used to constrain field types to only those defined in the field map.
+ *
+ * This type ensures type safety by only allowing field types that have been
+ * explicitly defined in the FieldMap interface. It prevents typos and ensures
+ * that all field types are known and properly configured.
+ *
+ * @type FieldType
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - defining a field with a valid type
+ * const textField: FieldBase<"text"> = {
+ *   type: "text", // ✓ Valid - "text" is in FieldMap
+ *   name: "username",
+ *   required: true
+ * };
+ *
+ * const emailField: FieldBase<"email"> = {
+ *   type: "email", // ✓ Valid - "email" is in FieldMap
+ *   name: "userEmail",
+ *   required: true
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Type-safe field type checking
+ * function createField<T extends FieldType>(
+ *   type: T,
+ *   config: Omit<FieldBase<T>, 'type'>
+ * ): FieldBase<T> {
+ *   return { type, ...config };
+ * }
+ *
+ * // Usage with type safety
+ * const numberField = createField("number", {
+ *   name: "age",
+ *   required: true,
+ *   min: 0,
+ *   max: 150
+ * });
+ *
+ * const dateField = createField("date", {
+ *   name: "birthDate",
+ *   required: false
+ * });
+ *
+ * // This would cause a TypeScript error:
+ * // const invalidField = createField("invalidType", { name: "test" });
+ * // Error: "invalidType" is not assignable to FieldType
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Dynamic field type validation
+ * function isValidFieldType(type: string): type is FieldType {
+ *   const validTypes: FieldType[] = ["text", "number", "boolean", "date", "email"];
+ *   return validTypes.includes(type as FieldType);
+ * }
+ *
+ * // Usage in runtime validation
+ * function validateFieldType(input: string): FieldType {
+ *   if (!isValidFieldType(input)) {
+ *     throw new Error(`Invalid field type: ${input}. Valid types are: text, number, boolean, date, email`);
+ *   }
+ *   return input;
+ * }
+ *
+ * // Safe usage
+ * const fieldType = validateFieldType("text"); // ✓ Valid
+ * // const invalidType = validateFieldType("invalid"); // ✗ Throws error
+ * ```
+ */
+export type FieldType = keyof FieldMap;
+/**
+ * ## Resources Interface
+ *
+ * A global interface for defining resource configurations in the application.
+ * This interface serves as a central registry for all available resources and their
+ * metadata, enabling type-safe resource management across the entire codebase.
+ *
+ * ### Purpose
+ * The `Resources` interface is designed for **module augmentation**, allowing developers
+ * to extend it with custom resource definitions. Each key represents a resource name
+ * (e.g., "users", "posts", "products"), and each value must conform to the `ResourceBase` interface,
+ * ensuring consistent structure and type safety for all resource configurations.
+ *
+ * ### How It Works
+ * - **Empty by Design**: The interface is intentionally empty in the core library.
+ * - **Module Augmentation**: Developers extend it via `declare module` statements.
+ * - **Type Safety**: The `ResourceConfig<T>`, `ResourceName`, and other types use `Resources[K]`
+ *   to enforce that resource configurations match their declared types.
+ * - **Extensibility**: New resources can be added without modifying the core library.
+ *
+ * ### Template Parameters
+ * This interface doesn't use generic parameters itself, but the values must conform to `ResourceBase<Name, DataType, TPrimaryKey, Actions>`.
+ *
+ * ### Examples
+ *
+ * #### Basic Module Augmentation
+ * ```typescript
+ * // In your application's types file (e.g., types.ts or global.d.ts)
+ * import "reslib/resources";
+ *
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     // Define a users resource
+ *     users: {
+ *       actions: {
+ *         read: { label: "Read User" };
+ *         create: { label: "Create User" };
+ *         update: { label: "Update User" };
+ *         delete: { label: "Delete User" };
+ *       }
+ *     };
+ *
+ *     // Define a posts resource
+ *     posts: {
+ *       actions: {
+ *         read: { label: "Read Post" };
+ *         create: { label: "Create Post" };
+ *         publish: { label: "Publish Post" };
+ *         archive: { label: "Archive Post" };
+ *       }
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * #### Advanced Resource Configuration
+ * ```typescript
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     // User resource with comprehensive actions
+ *     users: {
+ *       actions: {
+ *         read: { label: "Read User", title: "View user details" };
+ *         create: { label: "Create User", title: "Add new user" };
+ *         update: { label: "Update User", title: "Modify user data" };
+ *         delete: { label: "Delete User", title: "Remove user" };
+ *         activate: { label: "Activate User", title: "Enable user account" };
+ *         deactivate: { label: "Deactivate User", title: "Disable user account" };
+ *         resetPassword: { label: "Reset Password", title: "Send password reset" };
+ *       }
+ *     };
+ *
+ *     // Product resource with inventory management
+ *     products: {
+ *       actions: {
+ *         read: { label: "View Product" };
+ *         create: { label: "Add Product" };
+ *         update: { label: "Edit Product" };
+ *         delete: { label: "Remove Product" };
+ *         restock: { label: "Restock Product" };
+ *         discontinue: { label: "Discontinue Product" };
+ *       }
+ *     };
+ *
+ *     // Order resource with workflow actions
+ *     orders: {
+ *       actions: {
+ *         read: { label: "View Order" };
+ *         create: { label: "Create Order" };
+ *         update: { label: "Update Order" };
+ *         cancel: { label: "Cancel Order" };
+ *         ship: { label: "Ship Order" };
+ *         deliver: { label: "Mark Delivered" };
+ *         refund: { label: "Process Refund" };
+ *       }
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * #### Using Defined Resources
+ * ```typescript
+ * // After augmentation, you can use type-safe resource operations
+ * import { ResourceConfig, ResourceName, ResourceActions } from "reslib/resources";
+ *
+ * // Type-safe resource access
+ * type UserResource = ResourceConfig<"users">;
+ * type PostResource = ResourceConfig<"posts">;
+ *
+ * // Type-safe action names
+ * type UserActionNames = ResourceActionName<"users">;
+ * // Result: "read" | "create" | "update" | "delete" | "activate" | "deactivate" | "resetPassword"
+ *
+ * // Type-safe action access
+ * type UserActions = ResourceActions<"users">;
+ * // Result: Complete actions record for users resource
+ *
+ * // Runtime usage with type safety
+ * function processUserAction(action: UserActionNames, userId: string) {
+ *   console.log(`Processing ${action} for user ${userId}`);
+ *
+ *   // TypeScript ensures action is a valid user action
+ *   switch (action) {
+ *     case "create":
+ *       return createUser();
+ *     case "activate":
+ *       return activateUser(userId);
+ *     case "resetPassword":
+ *       return resetUserPassword(userId);
+ *     // TypeScript will catch invalid actions
+ *   }
+ * }
+ * ```
+ *
+ * #### Resource Registry Implementation
+ * ```typescript
+ * // Create a type-safe resource registry
+ * class ResourceRegistry {
+ *   private resources = new Map<ResourceName, ResourceConfig<ResourceName>>();
+ *
+ *   register<TResourceName extends ResourceName>(
+ *     name: TResourceName,
+ *     config: ResourceConfig<TResourceName>
+ *   ) {
+ *     this.resources.set(name, config);
+ *   }
+ *
+ *   get<TResourceName extends ResourceName>(
+ *     name: TResourceName
+ *   ): ResourceConfig<TResourceName> | undefined {
+ *     return this.resources.get(name) as ResourceConfig<TResourceName>;
+ *   }
+ *
+ *   getAllActions<TResourceName extends ResourceName>(
+ *     name: TResourceName
+ *   ): ResourceActions<TResourceName> {
+ *     const resource = this.get(name);
+ *     if (!resource) throw new Error(`Resource ${name} not found`);
+ *     return resource.actions;
+ *   }
+ * }
+ *
+ * // Usage
+ * const registry = new ResourceRegistry();
+ *
+ * registry.register("users", {
+ *   actions: {
+ *     read: { label: "Read User" },
+ *     create: { label: "Create User" },
+ *     update: { label: "Update User" }
+ *   }
+ * });
+ *
+ * const userActions = registry.getAllActions("users");
+ * // TypeScript knows this contains only user actions
+ * ```
+ *
+ * #### Permission System Integration
+ * ```typescript
+ * // Define permissions based on resource actions
+ * type Permission<TResourceName extends ResourceName> = {
+ *   resource: TResourceName;
+ *   action: ResourceActionName<TResourceName>;
+ *   granted: boolean;
+ * };
+ *
+ * class PermissionManager {
+ *   private permissions = new Map<string, Permission<ResourceName>>();
+ *
+ *   grant<TResourceName extends ResourceName>(
+ *     resource: TResourceName,
+ *     action: ResourceActionName<TResourceName>
+ *   ) {
+ *     const key = `${resource}:${action}`;
+ *     this.permissions.set(key, { resource, action, granted: true });
+ *   }
+ *
+ *   check<TResourceName extends ResourceName>(
+ *     resource: TResourceName,
+ *     action: ResourceActionName<TResourceName>
+ *   ): boolean {
+ *     const key = `${resource}:${action}`;
+ *     return this.permissions.get(key)?.granted ?? false;
+ *   }
+ * }
+ *
+ * // Usage
+ * const permManager = new PermissionManager();
+ *
+ * permManager.grant("users", "create");
+ * permManager.grant("users", "update");
+ * permManager.grant("posts", "publish");
+ *
+ * // Type-safe permission checks
+ * if (permManager.check("users", "create")) {
+ *   // User can create users
+ * }
+ *
+ * // This would cause a TypeScript error:
+ * // permManager.check("users", "invalidAction"); // ✗ Error: not a valid user action
+ * ```
+ *
+ * ### Best Practices
+ * - **Consistent Naming**: Use lowercase, plural resource names (e.g., "users", "products").
+ * - **Comprehensive Actions**: Define all relevant actions for each resource's lifecycle.
+ * - **Documentation**: Document custom resources and their actions clearly for team members.
+ * - **Versioning**: Consider the impact on existing code when adding new resources or actions.
+ * - **Validation**: Use TypeScript's type system to enforce resource constraints at compile time.
+ *
+ * ### Integration with Other Types
+ * - **ResourceConfig<T>**: Provides type-safe access to individual resource configurations.
+ * - **ResourceName**: Union type of all defined resource names.
+ * - **ResourceActions<T>**: Type-safe access to a resource's actions.
+ * - **ResourceActionName<T>**: Union type of action names for a specific resource.
+ * - **ResourceBase**: The base interface that all resource definitions must implement.
+ *
+ * ### Migration Notes
+ * If you're upgrading from a version where resources were defined differently,
+ * update your module augmentations to use this new structure for better type safety.
+ * Existing code using the old structure may need to be updated to match the new interface.
+ *
+ * @interface Resources
+ * @public
+ *
+ * @see {@link ResourceBase} - The base interface that resource definitions must implement
+ * @see {@link ResourceConfig} - How to access individual resource configurations
+ * @see {@link ResourceName} - The union type of all defined resource names
+ * @see {@link ResourceActions} - How to access resource actions with type safety
+ * @example
+ * ```typescript
+ * // Complete example of extending Resources
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     // User management resource
+ *     users: {
+ *       actions: {
+ *         read: { label: "Read User" };
+ *         create: { label: "Create User" };
+ *         update: { label: "Update User" };
+ *         delete: { label: "Delete User" };
+ *         activate: { label: "Activate User" };
+ *         deactivate: { label: "Deactivate User" };
+ *       }
+ *     };
+ *
+ *     // Content management resource
+ *     posts: {
+ *       actions: {
+ *         read: { label: "Read Post" };
+ *         create: { label: "Create Post" };
+ *         update: { label: "Update Post" };
+ *         delete: { label: "Delete Post" };
+ *         publish: { label: "Publish Post" };
+ *         archive: { label: "Archive Post" };
+ *       }
+ *     };
+ *
+ *     // E-commerce resource
+ *     products: {
+ *       actions: {
+ *         read: { label: "View Product" };
+ *         create: { label: "Add Product" };
+ *         update: { label: "Edit Product" };
+ *         delete: { label: "Remove Product" };
+ *         restock: { label: "Restock Product" };
+ *         discontinue: { label: "Discontinue Product" };
+ *       }
+ *     };
+ *
+ *     // Order management resource
+ *     orders: {
+ *       actions: {
+ *         read: { label: "View Order" };
+ *         create: { label: "Create Order" };
+ *         update: { label: "Update Order" };
+ *         cancel: { label: "Cancel Order" };
+ *         ship: { label: "Ship Order" };
+ *         deliver: { label: "Mark Delivered" };
+ *         refund: { label: "Process Refund" };
+ *       }
+ *     };
+ *   }
+ * }
+ *
+ * // Usage examples with type safety
+ * type UserResource = ResourceConfig<"users">;
+ * type UserActions = ResourceActionName<"users">;
+ *
+ * function handleUserAction(action: UserActions, userId: string) {
+ *   // TypeScript ensures action is a valid user action
+ *   console.log(`Handling ${action} for user ${userId}`);
+ * }
+ *
+ * // Valid usage
+ * handleUserAction("create", "123");
+ * handleUserAction("activate", "456");
+ *
+ * // Invalid usage (TypeScript error)
+ * // handleUserAction("invalidAction", "123"); // ✗ Error
+ * ```
+ */
+export interface Resources {
+}
+type ValidatedResources = {
+    [K in keyof Resources]: ValidateResource<Resources[K]>;
+};
+type ValidateResource<T> = T extends ResourceBase ? T : never;
+/**
+ * ## ResourceName Type
+ *
+ * A union type representing all valid resource names defined in the global Resources interface.
+ * This type provides compile-time safety by ensuring that only resources that have been
+ * properly defined and validated can be referenced throughout the application.
+ *
+ * ### Purpose
+ * The `ResourceName` type serves as the foundation for type-safe resource operations by
+ * creating a union of all resource names that have been defined via module augmentation.
+ * It ensures that developers can only reference resources that actually exist and conform
+ * to the expected structure, preventing typos and invalid resource references.
+ *
+ * ### How It Works
+ * - **Module Augmentation**: Resources are defined by extending the `Resources` interface
+ * - **Validation**: `ValidatedResources` ensures each resource implements `ResourceBase`
+ * - **Key Extraction**: `keyof ValidatedResources` creates a union of all valid resource names
+ * - **Type Safety**: Any operation using `ResourceName` is guaranteed to reference a valid resource
+ *
+ * ### Type Construction
+ * ```typescript
+ * ResourceName = keyof ValidatedResources
+ * ```
+ *
+ * Where `ValidatedResources` maps each resource to its validated configuration.
+ *
+ * ### Examples
+ *
+ * #### Basic Resource Definition and Usage
+ * ```typescript
+ * // Define resources via module augmentation
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     users: {
+ *       actions: {
+ *         read: { label: "Read User" };
+ *         create: { label: "Create User" };
+ *         update: { label: "Update User" };
+ *       }
+ *     };
+ *     posts: {
+ *       actions: {
+ *         read: { label: "Read Post" };
+ *         create: { label: "Create Post" };
+ *         publish: { label: "Publish Post" };
+ *       }
+ *     };
+ *     products: {
+ *       actions: {
+ *         read: { label: "View Product" };
+ *         create: { label: "Add Product" };
+ *         update: { label: "Edit Product" };
+ *       }
+ *     };
+ *   }
+ * }
+ *
+ * // ResourceName automatically becomes: "users" | "posts" | "products"
+ * type AvailableResources = ResourceName; // "users" | "posts" | "products"
+ *
+ * // Type-safe resource operations
+ * function getResourceConfig(name: ResourceName): ResourceConfig<ResourceName> {
+ *   // TypeScript ensures name is a valid resource
+ *   return getResourceConfiguration(name);
+ * }
+ *
+ * getResourceConfig("users");    // ✓ Valid
+ * getResourceConfig("posts");    // ✓ Valid
+ * getResourceConfig("products"); // ✓ Valid
+ * // getResourceConfig("invalid"); // ✗ TypeScript error
+ * ```
+ *
+ * #### Generic Functions with Resource Names
+ * ```typescript
+ * // Generic function that works with any resource
+ * function createResourceHandler<T extends ResourceName>(resourceName: T) {
+ *   return {
+ *     name: resourceName,
+ *     config: {} as ResourceConfig<T>,
+ *     actions: [] as ResourceActionName<T>[]
+ *   };
+ * }
+ *
+ * // Usage with type safety
+ * const userHandler = createResourceHandler("users");
+ * // TypeScript knows this is specifically for users
+ *
+ * const postHandler = createResourceHandler("posts");
+ * // TypeScript knows this is specifically for posts
+ * ```
+ *
+ * #### Resource Registry with Type Safety
+ * ```typescript
+ * // Type-safe resource registry
+ * class ResourceRegistry {
+ *   private resources = new Map<ResourceName, ResourceConfig<ResourceName>>();
+ *
+ *   register<T extends ResourceName>(
+ *     name: T,
+ *     config: ResourceConfig<T>
+ *   ): void {
+ *     this.resources.set(name, config);
+ *   }
+ *
+ *   get<T extends ResourceName>(name: T): ResourceConfig<T> | undefined {
+ *     return this.resources.get(name) as ResourceConfig<T> | undefined;
+ *   }
+ *
+ *   has(name: ResourceName): boolean {
+ *     return this.resources.has(name);
+ *   }
+ *
+ *   getAllResourceNames(): ResourceName[] {
+ *     return Array.from(this.resources.keys());
+ *   }
+ * }
+ *
+ * // Usage
+ * const registry = new ResourceRegistry();
+ *
+ * registry.register("users", {
+ *   actions: {
+ *     read: { label: "Read User" },
+ *     create: { label: "Create User" }
+ *   }
+ * });
+ *
+ * registry.register("posts", {
+ *   actions: {
+ *     read: { label: "Read Post" },
+ *     create: { label: "Create Post" }
+ *   }
+ * });
+ *
+ * // Type-safe access
+ * const userConfig = registry.get("users"); // ResourceConfig<"users">
+ * const postConfig = registry.get("posts"); // ResourceConfig<"posts">
+ * ```
+ *
+ * #### Permission System with Resource Names
+ * ```typescript
+ * // Permission type using ResourceName
+ * type ResourcePermission = {
+ *   resource: ResourceName;
+ *   action: string; // Could be ResourceActionName<ResourceName> for full type safety
+ *   granted: boolean;
+ * };
+ *
+ * class PermissionManager {
+ *   private permissions = new Map<string, ResourcePermission>();
+ *
+ *   grantPermission(resource: ResourceName, action: string): void {
+ *     const key = `${resource}:${action}`;
+ *     this.permissions.set(key, { resource, action, granted: true });
+ *   }
+ *
+ *   checkPermission(resource: ResourceName, action: string): boolean {
+ *     const key = `${resource}:${action}`;
+ *     return this.permissions.get(key)?.granted ?? false;
+ *   }
+ *
+ *   getAllPermissionsForResource(resource: ResourceName): ResourcePermission[] {
+ *     return Array.from(this.permissions.values())
+ *       .filter(perm => perm.resource === resource);
+ *   }
+ * }
+ *
+ * // Usage
+ * const permManager = new PermissionManager();
+ *
+ * permManager.grantPermission("users", "read");
+ * permManager.grantPermission("users", "create");
+ * permManager.grantPermission("posts", "read");
+ *
+ * permManager.checkPermission("users", "read");    // true
+ * permManager.checkPermission("users", "delete");  // false
+ * permManager.checkPermission("invalid", "read");  // ✗ TypeScript error
+ * ```
+ *
+ * #### API Route Generation
+ * ```typescript
+ * // Generate API routes for all defined resources
+ * function generateApiRoutes(resources: ResourceName[]): string[] {
+ *   const routes: string[] = [];
+ *
+ *   for (const resource of resources) {
+ *     routes.push(`/api/${resource}`);
+ *     routes.push(`/api/${resource}/:id`);
+ *   }
+ *
+ *   return routes;
+ * }
+ *
+ * // Usage
+ * const allRoutes = generateApiRoutes(["users", "posts", "products"]);
+ * // Result: ["/api/users", "/api/users/:id", "/api/posts", "/api/posts/:id", ...]
+ * ```
+ *
+ * ### Best Practices
+ * - **Module Augmentation**: Always define resources via `declare module` to extend the `Resources` interface
+ * - **Consistent Naming**: Use lowercase, plural resource names (e.g., "users", "products", "orders")
+ * - **Type Constraints**: Use `T extends ResourceName` in generic functions for type safety
+ * - **Validation**: Resources must implement `ResourceBase` to be included in `ResourceName`
+ * - **Documentation**: Document custom resources and their purposes for team members
+ *
+ * ### Integration with Other Types
+ * - **`Resources`**: The global interface that defines all resource configurations
+ * - **`ResourceConfig<T>`**: Provides type-safe access to individual resource configurations
+ * - **`ResourceActionName<T>`**: Union type of action names for a specific resource
+ * - **`ResourceActions<T>`**: Type-safe access to a resource's actions
+ * - **`ResourceBase`**: The base interface that all resources must implement
+ *
+ * ### Migration Notes
+ * When adding new resources, ensure they are defined via module augmentation of the `Resources`
+ * interface. The `ResourceName` type will automatically include new resources without requiring
+ * code changes elsewhere. Existing code using string literals for resource names can be updated
+ * to use `ResourceName` for better type safety.
+ *
+ * @type ResourceName
+ * @public
+ *
+ * @see {@link Resources} - The global interface defining all resource configurations
+ * @see {@link ResourceConfig} - How to access individual resource configurations
+ * @see {@link ResourceActionName} - Action names for specific resources
+ * @example
+ * ```typescript
+ * // Complete example of using ResourceName for type safety
+ * import "reslib/resources";
+ *
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     users: {
+ *       actions: {
+ *         read: { label: "Read User" };
+ *         create: { label: "Create User" };
+ *         update: { label: "Update User" };
+ *         delete: { label: "Delete User" };
+ *       };
+ *       permissions: {
+ *         adminOnly: string[];
+ *         publicAccess: string[];
+ *       };
+ *     };
+ *
+ *     posts: {
+ *       actions: {
+ *         read: { label: "Read Post" };
+ *         create: { label: "Create Post" };
+ *         publish: { label: "Publish Post" };
+ *         archive: { label: "Archive Post" };
+ *       };
+ *       categories: string[];
+ *     };
+ *
+ *     products: {
+ *       actions: {
+ *         read: { label: "View Product" };
+ *         create: { label: "Add Product" };
+ *         update: { label: "Edit Product" };
+ *         discontinue: { label: "Discontinue Product" };
+ *       };
+ *       pricing: {
+ *         currency: string;
+ *         taxRate: number;
+ *       };
+ *     };
+ *   }
+ * }
+ *
+ * // ResourceName is automatically: "users" | "posts" | "products"
+ * type AvailableResources = ResourceName;
+ *
+ * // Type-safe resource operations
+ * function processResource<T extends ResourceName>(name: T) {
+ *   console.log(`Processing resource: ${name}`);
+ *
+ *   // TypeScript knows the exact configuration available
+ *   const config = {} as ResourceConfig<T>;
+ *
+ *   // TypeScript knows the exact actions available
+ *   const actions = [] as ResourceActionName<T>[];
+ *
+ *   return { name, config, actions };
+ * }
+ *
+ * // Usage with full type safety
+ * const userProcessor = processResource("users");
+ * // userProcessor.name: "users"
+ * // userProcessor.config: ResourceConfig<"users">
+ * // userProcessor.actions: ResourceActionName<"users">[]
+ *
+ * const postProcessor = processResource("posts");
+ * // postProcessor.name: "posts"
+ * // postProcessor.config: ResourceConfig<"posts">
+ * // postProcessor.actions: ResourceActionName<"posts">[]
+ *
+ * // Invalid usage (TypeScript errors)
+ * // processResource("invalidResource"); // ✗ Error: not in ResourceName
+ * ```
+ */
+export type ResourceName = keyof ValidatedResources;
+/**
+ * ## ResourceConfig Type
+ *
+ * A type-safe accessor for individual resource configurations from the global Resources interface.
+ * This type provides compile-time guarantees that resource configurations conform to the expected structure
+ * and enables type-safe operations on specific resources throughout the application.
+ *
+ * ### Purpose
+ * The `ResourceConfig` type serves as a bridge between the global `Resources` interface and individual
+ * resource operations. It ensures that when you reference a specific resource by name, you get the
+ * exact configuration defined for that resource, with full type safety and IntelliSense support.
+ *
+ * ### How It Works
+ * This type uses TypeScript's indexed access types to extract the configuration for a specific resource:
+ *
+ * 1. **Type Validation**: Leverages `ValidatedResources` to ensure the resource configuration
+ *    implements the `ResourceBase` interface
+ * 2. **Indexed Access**: Uses `ValidatedResources[TResourceName]` to extract the specific resource config
+ * 3. **Type Safety**: Provides compile-time guarantees about the structure and available actions
+ * 4. **Extensibility**: Automatically reflects changes when new resources are added via module augmentation
+ *
+ * ### Template Parameters
+ * - **TResourceName**: The name of the resource (must be a key of the Resources interface).
+ *   This parameter is constrained to `ResourceName`, ensuring only defined resources can be accessed.
+ *
+ * ### Type Construction
+ * ```typescript
+ * ResourceConfig<TResourceName> = ValidatedResources[TResourceName]
+ * ```
+ *
+ * Where `ValidatedResources` ensures each resource configuration extends `ResourceBase`.
+ *
+ * ### Examples
+ *
+ * #### Basic Resource Access
+ * ```typescript
+ * // After defining resources via module augmentation
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     users: {
+ *       actions: {
+ *         read: { label: "Read User" };
+ *         create: { label: "Create User" };
+ *         update: { label: "Update User" };
+ *       }
+ *     };
+ *     posts: {
+ *       actions: {
+ *         read: { label: "Read Post" };
+ *         create: { label: "Create Post" };
+ *         publish: { label: "Publish Post" };
+ *       }
+ *     };
+ *   }
+ * }
+ *
+ * // Type-safe access to resource configurations
+ * type UserConfig = ResourceConfig<"users">;
+ * // Result: The complete configuration object for the users resource
+ *
+ * type PostConfig = ResourceConfig<"posts">;
+ * // Result: The complete configuration object for the posts resource
+ * ```
+ *
+ * #### Type-Safe Resource Operations
+ * ```typescript
+ * // Function that works with any resource configuration
+ * function createResourceHandler<TResourceName extends ResourceName>(
+ *   resourceName: TResourceName,
+ *   config: ResourceConfig<TResourceName>
+ * ) {
+ *   console.log(`Setting up handlers for ${resourceName}`);
+ *
+ *   // TypeScript knows the exact actions available for this resource
+ *   for (const actionName in config.actions) {
+ *     console.log(`Action: ${actionName}`);
+ *     // actionName is typed as keyof config.actions
+ *   }
+ *
+ *   return {
+ *     getConfig: (): ResourceConfig<TResourceName> => config,
+ *     getActionNames: (): (keyof ResourceConfig<TResourceName>['actions'])[] => {
+ *       return Object.keys(config.actions) as (keyof ResourceConfig<TResourceName>['actions'])[];
+ *     }
+ *   };
+ * }
+ *
+ * // Usage with type safety
+ * const userHandler = createResourceHandler("users", {
+ *   actions: {
+ *     read: { label: "Read User" },
+ *     create: { label: "Create User" },
+ *     update: { label: "Update User" }
+ *   }
+ * });
+ *
+ * // TypeScript ensures only valid user actions are used
+ * const userActions = userHandler.getActionNames();
+ * // Result: ("read" | "create" | "update")[]
+ * ```
+ *
+ * #### Resource Registry with Type Safety
+ * ```typescript
+ * // Type-safe resource registry
+ * class ResourceRegistry {
+ *   private resources = new Map<ResourceName, ResourceConfig<ResourceName>>();
+ *
+ *   register<TResourceName extends ResourceName>(
+ *     name: TResourceName,
+ *     config: ResourceConfig<TResourceName>
+ *   ) {
+ *     this.resources.set(name, config);
+ *   }
+ *
+ *   get<TResourceName extends ResourceName>(
+ *     name: TResourceName
+ *   ): ResourceConfig<TResourceName> | undefined {
+ *     return this.resources.get(name) as ResourceConfig<TResourceName> | undefined;
+ *   }
+ *
+ *   getAllActions<TResourceName extends ResourceName>(
+ *     name: TResourceName
+ *   ): ResourceConfig<TResourceName>['actions'] {
+ *     const resource = this.get(name);
+ *     if (!resource) throw new Error(`Resource ${name} not found`);
+ *     return resource.actions;
+ *   }
+ * }
+ *
+ * // Usage
+ * const registry = new ResourceRegistry();
+ *
+ * registry.register("users", {
+ *   actions: {
+ *     read: { label: "Read User" },
+ *     create: { label: "Create User" },
+ *     update: { label: "Update User" }
+ *   }
+ * });
+ *
+ * const userConfig = registry.get("users");
+ * // TypeScript knows this is ResourceConfig<"users">
+ *
+ * const userActions = registry.getAllActions("users");
+ * // TypeScript knows this contains only user actions
+ * ```
+ *
+ * #### Advanced Configuration with Custom Properties
+ * ```typescript
+ * // Resources with additional configuration properties
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     users: {
+ *       actions: {
+ *         read: { label: "Read User" };
+ *         create: { label: "Create User" };
+ *         update: { label: "Update User" };
+ *       };
+ *       // Custom properties
+ *       permissions: {
+ *         adminOnly: string[];
+ *         publicAccess: string[];
+ *       };
+ *       validationRules: {
+ *         passwordMinLength: number;
+ *         requireEmailVerification: boolean;
+ *       };
+ *     };
+ *   }
+ * }
+ *
+ * // Type-safe access to custom properties
+ * function configureUserResource(config: ResourceConfig<"users">) {
+ *   // TypeScript knows about custom properties
+ *   console.log("Admin actions:", config.permissions.adminOnly);
+ *   console.log("Password min length:", config.validationRules.passwordMinLength);
+ *
+ *   // Standard actions are still available
+ *   const actions = config.actions;
+ *   // actions is typed with user-specific actions
+ * }
+ *
+ * const userConfig: ResourceConfig<"users"> = {
+ *   actions: {
+ *     read: { label: "Read User" },
+ *     create: { label: "Create User" },
+ *     update: { label: "Update User" }
+ *   },
+ *   permissions: {
+ *     adminOnly: ["delete", "ban"],
+ *     publicAccess: ["read", "create"]
+ *   },
+ *   validationRules: {
+ *     passwordMinLength: 8,
+ *     requireEmailVerification: true
+ *   }
+ * };
+ *
+ * configureUserResource(userConfig);
+ * ```
+ *
+ * #### Generic Resource Processing
+ * ```typescript
+ * // Generic function that processes any resource
+ * function processResource<TResourceName extends ResourceName>(
+ *   name: TResourceName,
+ *   config: ResourceConfig<TResourceName>,
+ *   processor: (config: ResourceConfig<TResourceName>) => void
+ * ) {
+ *   console.log(`Processing resource: ${name}`);
+ *   processor(config);
+ * }
+ *
+ * // Usage with different resources
+ * processResource("users", userConfig, (config) => {
+ *   // config is typed as ResourceConfig<"users">
+ *   console.log("User actions:", Object.keys(config.actions));
+ * });
+ *
+ * processResource("posts", postConfig, (config) => {
+ *   // config is typed as ResourceConfig<"posts">
+ *   console.log("Post actions:", Object.keys(config.actions));
+ * });
+ * ```
+ *
+ * ### Best Practices
+ * - **Type Constraints**: Always use `TResourceName extends ResourceName` to constrain resource names
+ * - **Generic Functions**: Use generics to create reusable functions that work with any resource type
+ * - **Module Augmentation**: Define resources via module augmentation for better organization
+ * - **Type Safety**: Leverage TypeScript's inference to avoid manual type assertions
+ * - **Consistent Naming**: Use lowercase, plural resource names (e.g., "users", "products")
+ * - **Documentation**: Document custom resource properties for team members
+ *
+ * ### Integration with Other Types
+ * - **`Resources`**: The global interface that `ResourceConfig` accesses
+ * - **`ResourceName`**: Union type of all defined resource names
+ * - **`ResourceActions<TResourceName>`**: Type-safe access to a resource's actions
+ * - **`ResourceActionName<TResourceName>`**: Union type of action names for a specific resource
+ * - **`ResourceBase`**: The base interface that all resource configurations must implement
+ *
+ * ### Migration Notes
+ * When upgrading from direct resource object usage, replace explicit types with `ResourceConfig<TResourceName>`
+ * to gain type safety and automatic updates when resource definitions change. The type provides the same
+ * runtime behavior while adding compile-time guarantees.
+ *
+ * @type ResourceConfig
+ * @template TResourceName - The name of the resource (must be a key of Resources)
+ * @public
+ *
+ * @see {@link Resources} - The global interface defining all resource configurations
+ * @see {@link ResourceName} - Union type of all defined resource names
+ * @see {@link ResourceActions} - How to access resource actions with type safety
+ * @see {@link ResourceBase} - The base interface that resource definitions must implement
+ * @example
+ * ```typescript
+ * // Complete example of using ResourceConfig
+ * import "reslib/resources";
+ *
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     users: {
+ *       actions: {
+ *         read: { label: "Read User" };
+ *         create: { label: "Create User" };
+ *         update: { label: "Update User" };
+ *         delete: { label: "Delete User" };
+ *       };
+ *       permissions: {
+ *         adminOnly: string[];
+ *         publicAccess: string[];
+ *       };
+ *     };
+ *
+ *     products: {
+ *       actions: {
+ *         read: { label: "View Product" };
+ *         create: { label: "Add Product" };
+ *         update: { label: "Edit Product" };
+ *         discontinue: { label: "Discontinue Product" };
+ *       };
+ *       categories: string[];
+ *       pricing: {
+ *         currency: string;
+ *         taxRate: number;
+ *       };
+ *     };
+ *   }
+ * }
+ *
+ * // Type-safe resource configuration access
+ * type UserConfig = ResourceConfig<"users">;
+ * type ProductConfig = ResourceConfig<"products">;
+ *
+ * // Function that works with any resource configuration
+ * function setupResource<TResourceName extends ResourceName>(
+ *   name: TResourceName,
+ *   config: ResourceConfig<TResourceName>
+ * ) {
+ *   console.log(`Setting up ${name} resource`);
+ *
+ *   // Access standard properties
+ *   const actions = Object.keys(config.actions);
+ *   console.log(`Available actions: ${actions.join(', ')}`);
+ *
+ *   // Access resource-specific properties with type safety
+ *   if (name === "users") {
+ *     const userConfig = config as ResourceConfig<"users">;
+ *     console.log(`Admin actions: ${userConfig.permissions.adminOnly.join(', ')}`);
+ *   } else if (name === "products") {
+ *     const productConfig = config as ResourceConfig<"products">;
+ *     console.log(`Categories: ${productConfig.categories.join(', ')}`);
+ *     console.log(`Currency: ${productConfig.pricing.currency}`);
+ *   }
+ * }
+ *
+ * // Usage examples
+ * const userResource: ResourceConfig<"users"> = {
+ *   actions: {
+ *     read: { label: "Read User" },
+ *     create: { label: "Create User" },
+ *     update: { label: "Update User" },
+ *     delete: { label: "Delete User" }
+ *   },
+ *   permissions: {
+ *     adminOnly: ["delete"],
+ *     publicAccess: ["read", "create"]
+ *   }
+ * };
+ *
+ * const productResource: ResourceConfig<"products"> = {
+ *   actions: {
+ *     read: { label: "View Product" },
+ *     create: { label: "Add Product" },
+ *     update: { label: "Edit Product" },
+ *     discontinue: { label: "Discontinue Product" }
+ *   },
+ *   categories: ["electronics", "clothing", "books"],
+ *   pricing: {
+ *     currency: "USD",
+ *     taxRate: 0.08
+ *   }
+ * };
+ *
+ * setupResource("users", userResource);
+ * setupResource("products", productResource);
+ * ```
+ */
+export type ResourceConfig<TResourceName extends ResourceName> = ValidatedResources[TResourceName];
+/**
+ * Type representing the action names for a specific resource.
+ * This type extracts the literal action name strings from a resource's actions.
+ *
+ * This type provides compile-time safety by ensuring that only valid action names
+ * for a specific resource can be used. It preserves literal types, enabling better
+ * autocomplete and error detection.
+ *
+ * @type ResourceActionName
+ * @template TResourceName - The name of the resource (optional, defaults to all resources)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with specific resource
+ * import "reslib/resources";
+ *
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     users: {
+ *       actions: {
+ *         read: { label: "Read User" };
+ *         create: { label: "Create User" };
+ *         update: { label: "Update User" };
+ *         archive: { label: "Archive User" };
+ *       }
+ *     };
+ *   }
+ * }
+ *
+ * // Type-safe action names for users resource
+ * type UserActionName = ResourceActionName<"users">;
+ * // Result: "read" | "create" | "update" | "archive"
+ *
+ * function performUserAction(action: UserActionName) {
+ *   console.log(`Performing ${action} on user`);
+ * }
+ *
+ * performUserAction("read"); // ✓ Valid
+ * performUserAction("create"); // ✓ Valid
+ * // performUserAction("delete"); // ✗ TypeScript error - not a valid user action
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Generic function with resource-specific actions
+ * function createActionHandler<TResourceName extends ResourceName>(
+ *   resourceName: TResourceName,
+ *   actionName: ResourceActionName<TResourceName>
+ * ) {
+ *   return {
+ *     execute: () => console.log(`Executing ${actionName} on ${resourceName}`),
+ *     getActionName: (): ResourceActionName<TResourceName> => actionName
+ *   };
+ * }
+ *
+ * // Usage with type safety
+ * const userReadHandler = createActionHandler("users", "read");
+ * // TypeScript knows actionName must be a valid user action
+ *
+ * const userCreateHandler = createActionHandler("users", "create");
+ * // TypeScript knows actionName must be a valid user action
+ *
+ * // This would cause a TypeScript error:
+ * // const invalidHandler = createActionHandler("users", "delete");
+ * // Error: "delete" is not assignable to ResourceActionName<"users">
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Runtime action validation
+ * function isValidAction<TResourceName extends ResourceName>(
+ *   resourceName: TResourceName,
+ *   actionName: string
+ * ): actionName is ResourceActionName<TResourceName> {
+ *   // This would typically check against the resource's defined actions
+ *   const validActions = getResourceActions(resourceName);
+ *   return validActions.includes(actionName as ResourceActionName<TResourceName>);
+ * }
+ *
+ * // Usage
+ * if (isValidAction("users", "read")) {
+ *   // TypeScript now knows actionName is ResourceActionName<"users">
+ *   const handler = createActionHandler("users", "read");
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Action name arrays with type safety
+ * function getAllActionNames<TResourceName extends ResourceName>(
+ *   resourceName: TResourceName
+ * ): ResourceActionName<TResourceName>[] {
+ *   // Implementation would return all action names for the resource
+ *   return [] as ResourceActionName<TResourceName>[];
+ * }
+ *
+ * // Usage
+ * const userActions = getAllActionNames("users");
+ * // TypeScript knows userActions contains only valid user action names
+ *
+ * userActions.forEach(action => {
+ *   // action is typed as ResourceActionName<"users">
+ *   console.log(`User action: ${action}`);
+ * });
+ * ```
+ */
+export type ResourceActionName<TResourceName extends ResourceName = ResourceName> = GetResourceActionNames<ResourceConfig<TResourceName>>;
+/**
+ * @interface ResourceActionTuple
+ * Represents a tuple that contains a resource name and an action name.
+ * This type is a union of two possible tuple formats: `ResourceActionTupleArray` and `ResourceActionTupleObject`.
+ *
+ * @template TResourceName - The name of the resource. Defaults to `ResourceName`.
+ *
+ * @example
+ * ```typescript
+ * // Using ResourceActionTupleArray
+ * const actionTuple: ResourceActionTuple = ["users", "read"];
+ *
+ * // Using ResourceActionTupleObject
+ * const actionTuple: ResourceActionTuple = { resourceName: "users", action: "read" };
+ * ```
+ *
+ * @typeParam TResourceName - The name of the resource.
+ * @default ResourceName
+ *
+ * @typedef {(ResourceActionTupleArray<TResourceName> | ResourceActionTupleObject<TResourceName>)} ResourceActionTuple
+ *
+ * @see {@link ResourceActionTupleArray} for the `ResourceActionTupleArray` type.
+ * @see {@link ResourceActionTupleObject} for the `ResourceActionTupleObject` type.
+ */
+export type ResourceActionTuple<TResourceName extends ResourceName> = ResourceActionTupleArray<TResourceName> | ResourceActionTupleObject<TResourceName>;
+/**
+ * @interface ResourceActionTupleArray
+ * Represents a tuple that contains a resource name and an action name in an array format.
+ * This type is a tuple with two elements: the resource name and the action name.
+ *
+ * @template TResourceName - The name of the resource. Defaults to `ResourceName`.
+ *
+ * @example
+ * ```typescript
+ * const actionTuple: ResourceActionTupleArray = ["users", "read"];
+ * ```
+ *
+ * @typeParam TResourceName - The name of the resource.
+ * @default ResourceName
+ *
+ * @typedef {[TResourceName, ResourceActionName<TResourceName>]} ResourceActionTupleArray
+ */
+export type ResourceActionTupleArray<TResourceName extends ResourceName> = [
+    /**
+     * The name of the resource.
+     *
+     * @type {TResourceName}
+     */
+    TResourceName,
+    /**
+     * The name of the action.
+     *
+     * @type {ResourceActionName<TResourceName>}
+     */
+    ResourceActionName<TResourceName>
+];
+/**
+ * @interface ResourceActionTupleObject
+ * Represents a tuple that contains a resource name and an action name in an object format.
+ * This type is an object with two properties: `resourceName` and `action`.
+ *
+ * @template TResourceName - The name of the resource. Defaults to `ResourceName`.
+ *
+ * @example
+ * ```typescript
+ * const actionTuple: ResourceActionTupleObject = { resourceName: "users", action: "read" };
+ * ```
+ *
+ * @typeParam TResourceName - The name of the resource.
+ * @default ResourceName
+ *
+ * @interface ResourceActionTupleObject
+ */
+export interface ResourceActionTupleObject<TResourceName extends ResourceName> {
+    /**
+     * The name of the resource.
+     *
+     * @type {TResourceName}
+     */
+    resourceName: TResourceName;
+    /**
+     * The name of the action.
+     *
+     * @type {ResourceActionName<TResourceName>}
+     */
+    action: ResourceActionName<TResourceName>;
+}
+/**
+ * @interface ResourceAction
+ *
+ * Represents the structure of an action that can be performed on a resource within the application.
+ * This interface defines the essential properties that describe the action, allowing for a
+ * consistent representation of actions across different resources.
+ *
+ * ### Properties
+ *
+ * - `label` (optional): A user-friendly label for the action. This label is typically
+ *   displayed in the user interface (UI) to help users understand what the action does.
+ *   It should be concise and descriptive.
+ *
+ * - `title` (optional): A short text that appears when the user hovers over the action
+ *   in the UI. The title provides extra information about the action, helping users
+ *   understand its purpose without cluttering the interface.
+ *
+ * ### Example Usage
+ *
+ * Here is an example of how the `ResourceAction` interface can be utilized:
+ *
+ * ```typescript
+ * // Define a resource action for creating a new document
+ * const createDocumentAction: ResourceAction = {
+ *     label: "Create Document",
+ *     title: "Click to add a new document."
+ * };
+ *
+ * // Function to display action information
+ * function displayActionInfo(action: ResourceAction) {
+ *     console.log(`Action: ${action.label}`);
+ *     console.log(`Title: ${action.title}`);
+ * }
+ *
+ * // Example of displaying action information
+ * displayActionInfo(createDocumentAction);
+ * // Output:
+ * // Action: Create Document
+ * // Title: Create a new document in the system
+ * // Tooltip: Click to add a new document.
+ * ```
+ *
+ * ### Notes
+ *
+ * - The `ResourceAction` interface is designed to be flexible, allowing developers to
+ *   define actions with varying levels of details based on the needs of their application.
+ * - By providing clear labels, titles, and tooltips, developers can enhance the user
+ *   experience and make the application more intuitive.
+ */
+export interface ResourceAction {
+    label?: string;
+    title?: string;
+}
+type ResourceActionsRecord<TActions> = TActions extends Record<string, ResourceAction> ? TActions & Partial<ResourceDefaultActions> : never;
+/**
+ * Type representing the actions record for a specific resource.
+ * This type extracts the actions from a resource's definition, ensuring type safety.
+ *
+ * This type provides access to the complete actions object for a resource,
+ * maintaining the exact structure and types as defined in the resource's configuration.
+ * It's useful when you need to work with the entire set of actions for a resource.
+ *
+ * @type ResourceActions
+ * @template TResourceName - The name of the resource
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - getting resource actions type
+ * import "reslib/resources";
+ *
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     users: {
+ *       actions: {
+ *         read: { label: "Read User", title: "View user details" };
+ *         create: { label: "Create User", title: "Add new user" };
+ *         update: { label: "Update User", title: "Modify user data" };
+ *         archive: { label: "Archive User", title: "Soft delete user" };
+ *       }
+ *     };
+ *   }
+ * }
+ *
+ * // Type-safe access to user actions
+ * type UserActions = ResourceActions<"users">;
+ * // Result: The complete actions record for users resource
+ *
+ * const userActions: UserActions = {
+ *   read: { label: "Read User", title: "View user details" },
+ *   create: { label: "Create User", title: "Add new user" },
+ *   update: { label: "Update User", title: "Modify user data" },
+ *   archive: { label: "Archive User", title: "Soft delete user" }
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Function that works with resource actions
+ * function validateResourceActions<TResourceName extends ResourceName>(
+ *   resourceName: TResourceName,
+ *   actions: ResourceActions<TResourceName>
+ * ): boolean {
+ *   // Check if all required actions are present
+ *   const requiredActions: (keyof ResourceActions<TResourceName>)[] = ['read', 'create', 'update'];
+ *
+ *   return requiredActions.every(action =>
+ *     action in actions && actions[action] !== undefined
+ *   );
+ * }
+ *
+ * // Usage
+ * const validUserActions = validateResourceActions("users", {
+ *   read: { label: "Read" },
+ *   create: { label: "Create" },
+ *   update: { label: "Update" },
+ *   archive: { label: "Archive" }
+ * }); // Returns true
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Building action handlers with type safety
+ * function createActionHandlers<TResourceName extends ResourceName>(
+ *   resourceName: TResourceName,
+ *   actions: ResourceActions<TResourceName>
+ * ) {
+ *   const handlers: Record<string, () => void> = {};
+ *
+ *   // TypeScript knows the exact action names available
+ *   for (const actionName in actions) {
+ *     handlers[actionName] = () => {
+ *       const action = actions[actionName as keyof ResourceActions<TResourceName>];
+ *       console.log(`Executing ${action?.label} on ${resourceName}`);
+ *     };
+ *   }
+ *
+ *   return handlers;
+ * }
+ *
+ * // Usage
+ * const userActionHandlers = createActionHandlers("users", {
+ *   read: { label: "Read User" },
+ *   create: { label: "Create User" },
+ *   update: { label: "Update User" }
+ * });
+ *
+ * userActionHandlers.read(); // ✓ Valid - calls read handler
+ * userActionHandlers.create(); // ✓ Valid - calls create handler
+ * // userActionHandlers.delete(); // ✗ TypeScript error - delete not in user actions
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Permission system based on resource actions
+ * class PermissionManager {
+ *   private permissions = new Map<ResourceName, Set<string>>();
+ *
+ *   grantPermission<TResourceName extends ResourceName>(
+ *     resourceName: TResourceName,
+ *     actions: (keyof ResourceActions<TResourceName>)[]
+ *   ) {
+ *     const current = this.permissions.get(resourceName) || new Set();
+ *     actions.forEach(action => current.add(action as string));
+ *     this.permissions.set(resourceName, current);
+ *   }
+ *
+ *   hasPermission<TResourceName extends ResourceName>(
+ *     resourceName: TResourceName,
+ *     action: keyof ResourceActions<TResourceName>
+ *   ): boolean {
+ *     const resourcePerms = this.permissions.get(resourceName);
+ *     return resourcePerms?.has(action as string) ?? false;
+ *   }
+ * }
+ *
+ * // Usage
+ * const permManager = new PermissionManager();
+ * permManager.grantPermission("users", ["read", "create"]);
+ *
+ * permManager.hasPermission("users", "read"); // true
+ * permManager.hasPermission("users", "update"); // false
+ * // permManager.hasPermission("users", "invalid"); // ✗ TypeScript error
+ * ```
+ */
+export type ResourceActions<TResourceName extends ResourceName> = Resources[TResourceName] extends {
+    actions: Record<string, ResourceAction>;
+} ? ResourceActionsRecord<Resources[TResourceName]['actions']> : never;
+type GetResourceActionNames<TResource extends {
+    actions?: Record<string, ResourceAction>;
+}> = keyof ResourceActionsRecord<TResource['actions']> & string;
+/**
+ * ## ResourceDefaultActions Interface
+ *
+ * A foundational interface defining the standard CRUD (Create, Read, Update, Delete) actions
+ * that can be performed on resources, plus an "all" action for comprehensive permissions.
+ * This interface serves as the base set of actions that resource configurations can extend,
+ * override, or supplement with custom actions.
+ *
+ * ### Purpose
+ * The `ResourceDefaultActions` interface establishes a consistent set of core actions that
+ * most resources will support. It provides a standardized foundation for resource management
+ * while allowing flexibility for custom actions specific to particular resources.
+ *
+ * ### How It Works
+ * - **Base Actions**: Defines the five fundamental actions (read, create, update, delete, all)
+ * - **Extensibility**: Used in `ResourceActionsRecord` to create action records that can be extended
+ * - **Type Safety**: Each action is typed as `ResourceAction`, ensuring consistent structure
+ * - **Optional Override**: Resources can override these defaults or add custom actions alongside them
+ *
+ * ### Default Actions
+ *
+ * - **`read`**: Retrieve/view resource data (GET operations)
+ * - **`create`**: Create new resource instances (POST operations)
+ * - **`update`**: Modify existing resource instances (PUT/PATCH operations)
+ * - **`delete`**: Remove resource instances (DELETE operations)
+ * - **`all`**: Perform any action on the resource (wildcard permission)
+ *
+ * ### Template Parameters
+ * This interface doesn't use generic parameters itself, but serves as a foundation for
+ * action-based type operations and resource configurations.
+ *
+ * ### Examples
+ *
+ * #### Basic Resource with Default Actions
+ * ```typescript
+ * // A simple resource using only default actions
+ * const userResource: ResourceBase = {
+ *   name: "users",
+ *   label: "Users",
+ *   actions: {
+ *     read: { label: "View Users" },
+ *     create: { label: "Create User" },
+ *     update: { label: "Update User" },
+ *     delete: { label: "Delete User" },
+ *     all: { label: "Full User Access" }
+ *   }
+ * };
+ * ```
+ *
+ * #### Resource Extending Default Actions
+ * ```typescript
+ * // Resource with default actions plus custom ones
+ * const blogResource: ResourceBase = {
+ *   name: "posts",
+ *   label: "Blog Posts",
+ *   actions: {
+ *     // Default actions
+ *     read: { label: "View Posts" },
+ *     create: { label: "Write Post" },
+ *     update: { label: "Edit Post" },
+ *     delete: { label: "Delete Post" },
+ *     all: { label: "Full Post Access" },
+ *
+ *     // Custom actions
+ *     publish: { label: "Publish Post" },
+ *     archive: { label: "Archive Post" },
+ *     feature: { label: "Feature Post" }
+ *   }
+ * };
+ * ```
+ *
+ * #### Permission System Using Default Actions
+ * ```typescript
+ * // Permission checking with default actions
+ * class PermissionManager {
+ *   private permissions = new Map<string, Set<string>>();
+ *
+ *   grantDefaultActions(resourceName: string) {
+ *     const key = `resource:${resourceName}`;
+ *     const actions = this.permissions.get(key) || new Set();
+ *
+ *     // Grant all default actions
+ *     actions.add('read');
+ *     actions.add('create');
+ *     actions.add('update');
+ *     actions.add('delete');
+ *
+ *     this.permissions.set(key, actions);
+ *   }
+ *
+ *   hasPermission(resourceName: string, action: keyof ResourceDefaultActions): boolean {
+ *     const key = `resource:${resourceName}`;
+ *     const actions = this.permissions.get(key);
+ *     return actions?.has(action) ?? false;
+ *   }
+ * }
+ *
+ * // Usage
+ * const permManager = new PermissionManager();
+ * permManager.grantDefaultActions('users');
+ *
+ * permManager.hasPermission('users', 'read');    // true
+ * permManager.hasPermission('users', 'create');  // true
+ * permManager.hasPermission('users', 'delete');  // true
+ * permManager.hasPermission('users', 'all');     // false (not granted)
+ * ```
+ *
+ * #### UI Component with Action-Based Rendering
+ * ```typescript
+ * // Component that renders different UI based on available actions
+ * interface ResourceActionButtonProps {
+ *   resourceName: string;
+ *   action: keyof ResourceDefaultActions;
+ *   onClick: () => void;
+ *   children: React.ReactNode;
+ * }
+ *
+ * function ResourceActionButton({
+ *   resourceName,
+ *   action,
+ *   onClick,
+ *   children
+ * }: ResourceActionButtonProps) {
+ *   const hasPermission = usePermission(resourceName, action);
+ *
+ *   if (!hasPermission) return null;
+ *
+ *   return (
+ *     <button onClick={onClick} data-action={action}>
+ *       {children}
+ *     </button>
+ *   );
+ * }
+ *
+ * // Usage in a resource management component
+ * function UserManagement() {
+ *   return (
+ *     <div>
+ *       <ResourceActionButton resourceName="users" action="create">
+ *         Add User
+ *       </ResourceActionButton>
+ *
+ *       <ResourceActionButton resourceName="users" action="read">
+ *         View Users
+ *       </ResourceActionButton>
+ *
+ *       <ResourceActionButton resourceName="users" action="update">
+ *         Edit User
+ *       </ResourceActionButton>
+ *
+ *       <ResourceActionButton resourceName="users" action="delete">
+ *         Delete User
+ *       </ResourceActionButton>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * #### API Route Protection
+ * ```typescript
+ * // Middleware for protecting API routes based on default actions
+ * function requireAction(resourceName: string, action: keyof ResourceDefaultActions) {
+ *   return (req: Request, res: Response, next: NextFunction) => {
+ *     const user = getCurrentUser(req);
+ *     const hasPermission = checkUserPermission(user, resourceName, action);
+ *
+ *     if (!hasPermission) {
+ *       return res.status(403).json({
+ *         error: 'Forbidden',
+ *         message: `You don't have permission to ${action} ${resourceName}`
+ *       });
+ *     }
+ *
+ *     next();
+ *   };
+ * }
+ *
+ * // Usage in Express routes
+ * app.get('/api/users', requireAction('users', 'read'), getUsers);
+ * app.post('/api/users', requireAction('users', 'create'), createUser);
+ * app.put('/api/users/:id', requireAction('users', 'update'), updateUser);
+ * app.delete('/api/users/:id', requireAction('users', 'delete'), deleteUser);
+ * ```
+ *
+ * #### Form Validation Based on Actions
+ * ```typescript
+ * // Form component that adapts based on available actions
+ * interface SmartFormProps<T> {
+ *   resourceName: string;
+ *   initialData?: T;
+ *   onSubmit: (data: T) => void;
+ * }
+ *
+ * function SmartForm<T>({ resourceName, initialData, onSubmit }: SmartFormProps<T>) {
+ *   const canCreate = usePermission(resourceName, 'create');
+ *   const canUpdate = usePermission(resourceName, 'update');
+ *   const isEditing = !!initialData;
+ *
+ *   // Don't render form if no appropriate permissions
+ *   if (isEditing && !canUpdate) return { error: 'No permission to edit' };
+ *   if (!isEditing && !canCreate) return { error: 'No permission to create' };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit(onSubmit)}>
+ *       <button type="submit">
+ *         {isEditing ? 'Update' : 'Create'}
+ *       </button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * ### Best Practices
+ * - **Consistent Action Names**: Always use the standard action names (read, create, update, delete, all)
+ * - **Clear Labels**: Provide descriptive labels for each action in resource definitions
+ * - **Permission Granularity**: Use specific actions rather than relying only on "all"
+ * - **Documentation**: Document custom actions that extend beyond the defaults
+ * - **UI Consistency**: Use these actions consistently across different UI components
+ *
+ * ### Integration with Other Types
+ * - **`ResourceActions<T>`**: Uses this interface as the base for resource-specific actions
+ * - **`ResourceActionName<T>`**: Provides type-safe action names for specific resources
+ * - **`ResourceBase`**: Resources can extend or override these default actions
+ * - **`ResourceAction`**: The type definition for individual actions
+ *
+ * ### Migration Notes
+ * When upgrading from custom action definitions, map your existing actions to these standard
+ * names where possible. The "all" action can be used for comprehensive permissions that
+ * previously used different naming conventions.
+ *
+ * @interface ResourceDefaultActions
+ * @public
+ *
+ * @see {@link ResourceActions} - How these actions are used in resource configurations
+ * @see {@link ResourceAction} - The structure of individual actions
+ * @see {@link ResourceBase} - How resources define their available actions
+ * @example
+ * ```typescript
+ * // Complete example of using ResourceDefaultActions in a resource definition
+ * import "reslib/resources";
+ *
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     users: {
+ *       actions: ResourceDefaultActions & {
+ *         // Extend with custom actions
+ *         resetPassword: { label: "Reset Password" };
+ *         activate: { label: "Activate Account" };
+ *         deactivate: { label: "Deactivate Account" };
+ *       }
+ *     };
+ *
+ *     products: {
+ *       actions: ResourceDefaultActions & {
+ *         // Product-specific actions
+ *         restock: { label: "Restock Product" };
+ *         discontinue: { label: "Discontinue Product" };
+ *         feature: { label: "Feature Product" };
+ *       }
+ *     };
+ *   }
+ * }
+ *
+ * // Type-safe usage
+ * type UserActions = ResourceActions<"users">;
+ * // Includes: read, create, update, delete, all, resetPassword, activate, deactivate
+ *
+ * type ProductActions = ResourceActions<"products">;
+ * // Includes: read, create, update, delete, all, restock, discontinue, feature
+ *
+ * // Permission checking function
+ * function canPerformAction<T extends ResourceName>(
+ *   resource: T,
+ *   action: keyof ResourceActions<T>
+ * ): boolean {
+ *   // Implementation would check user permissions
+ *   return true; // Simplified for example
+ * }
+ *
+ * // Usage
+ * canPerformAction("users", "create");        // ✓ Valid - default action
+ * canPerformAction("users", "resetPassword"); // ✓ Valid - custom action
+ * canPerformAction("users", "restock");       // ✗ TypeScript error - not a user action
+ * ```
+ */
+export interface ResourceDefaultActions {
+    /**
+     * The read action for the resource.
+     * This action is used to retrieve a specific resource.
+     *
+     * @type {ResourceAction}
+     * @example
+     * ```typescript
+     * const readAction: ResourceAction = {
+     *     label: "Read Resource",
+     *     title: "Click to read a specific resource.",
+     * };
+     * ```
+     */
+    read: ResourceAction;
+    /**
+     * The create action for the resource.
+     * This action is used to create a new resource.
+     *
+     * @type {ResourceAction}
+     * @example
+     * ```typescript
+     * const createAction: ResourceAction = {
+     *     label: "Create Resource",
+     *     title: "Click to create a new resource.",
+     * };
+     * ```
+     */
+    create: ResourceAction;
+    /**
+     * The update action for the resource.
+     * This action is used to update a specific resource.
+     *
+     * @type {ResourceAction}
+     * @example
+     * ```typescript
+     * const updateAction: ResourceAction = {
+     *     label: "Update Resource",
+     *     title: "Click to update a specific resource.",
+     * };
+     * ```
+     */
+    update: ResourceAction;
+    /**
+     * The delete action for the resource.
+     * This action is used to delete a specific resource.
+     *
+     * @type {ResourceAction}
+     * @example
+     * ```typescript
+     * const deleteAction: ResourceAction = {
+     *     label: "Delete Resource",
+     *     title: "Click to delete a specific resource.",
+     * };
+     * ```
+     */
+    delete: ResourceAction;
+    /**
+     * The all action for the resource.
+     * This action is used to perform all actions on the resource.
+     *
+     * @type {ResourceAction}
+     * @example
+     * ```typescript
+     * const allAction: ResourceAction = {
+     *     label: "All Actions",
+     *     title: "Click to perform all actions on the resource.",
+     * };
+     * ```
+     */
+    all: ResourceAction;
+}
+/**
+ * ## ResourceBase Interface
+ *
+ * The foundational interface that defines the structure and properties required for all resources
+ * in the application. This interface serves as the base contract that all resource definitions
+ * must implement to be considered valid within the resource management system.
+ *
+ * ### Purpose
+ * The `ResourceBase` interface establishes the minimum structure that every resource must have,
+ * ensuring consistency and type safety across all resource definitions. It acts as a constraint
+ * that validates resource configurations during module augmentation, preventing invalid or
+ * incomplete resource definitions from being accepted by the type system.
+ *
+ * ### How It Works
+ * - **Module Augmentation**: Resources are defined by extending the global `Resources` interface
+ * - **Validation**: The `ValidateResource<T>` type ensures each resource implements `ResourceBase`
+ * - **Type Safety**: Only resources that conform to this interface are included in `ResourceName`
+ * - **Extensibility**: Generic parameters allow resources to specify their own action types
+ *
+ * ### Template Parameters
+ * - **TResourceName**: The specific resource name type (extends `ResourceName`)
+ * - **Actions**: The record of actions available for this resource (extends `Record<string, ResourceAction>`)
+ *
+ * ### Examples
+ *
+ * #### Basic Resource Definition
+ * ```typescript
+ * // Define a simple user resource
+ * const userResource: ResourceBase<"users"> = {
+ *   name: "users",
+ *   label: "Users",
+ *   title: "User Management",
+ *   actions: {
+ *     read: { label: "Read User" },
+ *     create: { label: "Create User" },
+ *     update: { label: "Update User" }
+ *   }
+ * };
+ * ```
+ *
+ * #### Advanced Resource with Custom Actions
+ * ```typescript
+ * // Define a product resource with custom actions
+ * const productResource: ResourceBase<"products", {
+ *   read: ResourceAction;
+ *   create: ResourceAction;
+ *   update: ResourceAction;
+ *   discontinue: ResourceAction;
+ *   restock: ResourceAction;
+ * }> = {
+ *   name: "products",
+ *   label: "Products",
+ *   title: "Product Catalog Management",
+ *   actions: {
+ *     read: { label: "View Product", title: "Display product details" },
+ *     create: { label: "Add Product", title: "Create new product entry" },
+ *     update: { label: "Edit Product", title: "Modify product information" },
+ *     discontinue: { label: "Discontinue Product", title: "Mark product as discontinued" },
+ *     restock: { label: "Restock Product", title: "Update product inventory" }
+ *   }
+ * };
+ * ```
+ *
+ * #### Module Augmentation Usage
+ * ```typescript
+ * // In your application's types file
+ * import "reslib/resources";
+ *
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     // All of these must implement ResourceBase
+ *     users: {
+ *       name: "users";
+ *       label: "Users";
+ *       actions: {
+ *         read: { label: "Read User" };
+ *         create: { label: "Create User" };
+ *       };
+ *     };
+ *
+ *     posts: {
+ *       name: "posts";
+ *       label: "Posts";
+ *       title: "Blog Posts";
+ *       actions: {
+ *         read: { label: "Read Post" };
+ *         publish: { label: "Publish Post" };
+ *       };
+ *     };
+ *   }
+ * }
+ *
+ * // TypeScript will enforce ResourceBase structure
+ * // Invalid resources will cause compilation errors
+ * ```
+ *
+ * #### Type-Safe Resource Operations
+ * ```typescript
+ * // Using ResourceBase for type-safe operations
+ * function createResourceHandler<T extends ResourceBase>(
+ *   resource: T
+ * ): ResourceHandler<T> {
+ *   return {
+ *     name: resource.name,
+ *     label: resource.label,
+ *     actions: Object.keys(resource.actions),
+ *     // TypeScript knows resource has name, label, and actions
+ *   };
+ * }
+ *
+ * const userHandler = createResourceHandler(userResource);
+ * // userHandler.name: "users"
+ * // userHandler.label: "Users"
+ * // userHandler.actions: string[]
+ * ```
+ *
+ * #### Resource Validation
+ * ```typescript
+ * // Custom validation using ResourceBase structure
+ * function validateResource(resource: any): resource is ResourceBase {
+ *   return (
+ *     typeof resource === 'object' &&
+ *     typeof resource.name === 'string' &&
+ *     typeof resource.actions === 'object' &&
+ *     resource.actions !== null
+ *   );
+ * }
+ *
+ * // Usage
+ * if (validateResource(someResource)) {
+ *   // TypeScript knows this is a ResourceBase
+ *   console.log(`Valid resource: ${someResource.name}`);
+ * }
+ * ```
+ *
+ * ### Best Practices
+ * - **Consistent Naming**: Use lowercase resource names (e.g., "users", "products")
+ * - **Descriptive Labels**: Provide clear, user-friendly labels for UI display
+ * - **Comprehensive Actions**: Define all relevant actions for the resource's lifecycle
+ * - **Optional Properties**: Use `label` and `title` for better UX, but they're optional
+ * - **Type Safety**: Leverage the generic parameters for precise action typing
+ * - **Documentation**: Document custom actions and their purposes
+ *
+ * ### Integration with Other Types
+ * - **`Resources`**: Global interface where resources are defined via module augmentation
+ * - **`ResourceName`**: Union type of all valid resource names (requires ResourceBase compliance)
+ * - **`ResourceConfig<T>`**: Provides type-safe access to individual resource configurations
+ * - **`ResourceActions<T>`**: Type-safe access to a resource's actions
+ * - **`ValidateResource<T>`**: Type-level validation that checks ResourceBase implementation
+ * - **`ValidatedResources`**: Maps all resources to ensure they extend ResourceBase
+ *
+ * ### Migration Notes
+ * When adding new resources, ensure they implement all required `ResourceBase` properties.
+ * The `name` property must match the key used in the `Resources` interface. Existing
+ * resources that don't conform to this interface will cause TypeScript compilation errors
+ * after upgrading, helping catch configuration issues early.
+ *
+ * @interface ResourceBase
+ * @template TResourceName - The specific resource name type
+ * @template Actions - The record of actions for this resource
+ * @public
+ *
+ * @see {@link Resources} - Global interface for resource definitions
+ * @see {@link ResourceName} - Union of all valid resource names
+ * @see {@link ResourceConfig} - Type-safe resource configuration access
+ * @see {@link ValidateResource} - Type-level validation of resource structure
+ * @example
+ * ```typescript
+ * // Complete example of ResourceBase usage
+ * import "reslib/resources";
+ *
+ * // Define custom action types for better type safety
+ * interface UserActions {
+ *   read: ResourceAction;
+ *   create: ResourceAction;
+ *   update: ResourceAction;
+ *   delete: ResourceAction;
+ *   activate: ResourceAction;
+ *   deactivate: ResourceAction;
+ * }
+ *
+ * // Create a fully typed resource
+ * const userResource: ResourceBase<"users", UserActions> = {
+ *   name: "users",
+ *   label: "Users",
+ *   title: "User Account Management",
+ *   actions: {
+ *     read: {
+ *       label: "Read User",
+ *       title: "View user account details"
+ *     },
+ *     create: {
+ *       label: "Create User",
+ *       title: "Add new user account"
+ *     },
+ *     update: {
+ *       label: "Update User",
+ *       title: "Modify user account information"
+ *     },
+ *     delete: {
+ *       label: "Delete User",
+ *       title: "Remove user account"
+ *     },
+ *     activate: {
+ *       label: "Activate User",
+ *       title: "Enable user account access"
+ *     },
+ *     deactivate: {
+ *       label: "Deactivate User",
+ *       title: "Disable user account access"
+ *     }
+ *   }
+ * };
+ *
+ * // Module augmentation for global availability
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     users: typeof userResource;
+ *   }
+ * }
+ *
+ * // Type-safe usage throughout the application
+ * type UserName = "users"; // From ResourceName union
+ * type UserConfig = ResourceConfig<"users">; // Full type safety
+ * type UserActionNames = ResourceActionName<"users">; // "read" | "create" | "update" | ...
+ * ```
+ */
+export interface ResourceBase<TResourceName extends ResourceName = ResourceName, Actions extends Record<string, ResourceAction> = Record<string, ResourceAction>> {
+    /**
+     * The internal name of the resource.
+     *
+     * This name is used within the system for referencing the resource programmatically.
+     * It is often a short, unique identifier for the resource.
+     *
+     * @example
+     * ```typescript
+     * const userResource: ResourceBase = { name: "user" };
+     * ```
+     */
+    name: TResourceName;
+    /**
+     * A user-friendly label for the resource.
+     *
+     * This is typically a shorter name intended for display in UI elements, such as dropdowns or buttons.
+     * It helps users identify the resource within the user interface.
+     *
+     * @example
+     * ```typescript
+     * const productResource: ResourceBase = { label: "Product" };
+     * ```
+     */
+    label?: string;
+    /**
+     * A short text that appears when the user hovers over the resource.
+     * The title provides additional context or information about the resource.
+     *
+     * Typically used in user interfaces to clarify what a particular resource represents or to give instructions.
+     *
+     * @example
+     * ```typescript
+     * const userResource: ResourceBase = { title: "This resource manages user information." };
+     * ```
+     */
+    title?: string;
+    /**
+     * The actions associated with this resource.
+     * This is a well-typed record that preserves key inference while satisfying Record<string, ResourceAction>.
+     *
+     * @example
+     * ```typescript
+     * const userResource: ResourceBase = {
+     *   actions: {
+     *     read: { label: "Read User" },
+     *     create: { label: "Create User" },
+     *     archive: { label: "Archive User" } // Custom action
+     *   }
+     * };
+     *
+     * // TypeScript infers: "read" | "create" | "archive"
+     * type UserActionNames = GetResourceActionNames<typeof userResource>;
+     *
+     * // Still compatible with generic Record<string, ResourceAction>
+     * const genericActions: Record<string, ResourceAction> = userResource.actions;
+     * ```
+     */
+    actions: ResourceActionsRecord<Actions>;
+}
+/**
+ * @type ResourcePrimaryKey
+ *
+ * Represents the type of primary keys that can be utilized in a resource.
+ * This type is a union that provides flexibility in defining unique identifiers
+ * for resources, accommodating various data structures and use cases.
+ *
+ * ### Possible Forms:
+ *
+ * - **Record<string, string | number>**: An object where the keys are strings
+ *   and the values can be either strings or numbers. This allows for composite keys
+ *   that consist of multiple fields.
+ *   - **Example**:
+ *     ```typescript
+ *     const compositeKey: TPrimaryKey = { userId: "user123", orderId: 456 };
+ *     // A composite key representing a user and their order
+ *     ```
+ *
+ * ### Notes:
+ * - This type is particularly useful in scenarios where resources may have
+ *   different types of identifiers, such as in databases or APIs.
+ * - Using a `Record` allows for more complex primary key structures, which can
+ *   be beneficial in applications that require composite keys.
+ *
+ * ### Use Cases:
+ * - Defining primary keys in database models.
+ * - Creating unique identifiers for API resources.
+ * - Handling composite keys in data structures.
+ *
+ * ### Related Types:
+ * - Consider using `ResourceBase` for defining the overall structure of a resource
+ *   that utilizes this primary key type.
+ *
+ * ### Example Usage:
+ * Here’s how you might use the `ResourcePrimaryKey` type in a function that
+ * retrieves a resource by its primary key:
+ *
+ * ```typescript
+ * function getResourceById(id: TPrimaryKey): ResourceMeta {
+ *     // Implementation to list the resource based on the provided primary key
+ * }
+ *
+ * const resource = getResourceById("user123"); // Fetching by string ID
+ * const anotherResource = getResourceById(456); // Fetching by numeric ID
+ * const compositeResource = getResourceById({ userId: "user123", orderId: 456 }); // Fetching by composite key
+ * ```
+ *
+ * ### Summary:
+ * The `ResourcePrimaryKey` type provides a versatile way to define primary keys
+ * for resources, supporting simple and complex identifiers. This flexibility is
+ * essential for applications that manage diverse data structures and require
+ * unique identification of resources.
+ */
+export type ResourcePrimaryKey = string | number | object;
+/**
+ * @interface ResourceDataService
+ *
+ * Represents a data provider interface for managing resources.
+ * This interface defines methods for performing CRUD (Create, Read, Update, Delete)
+ * operations on resources, allowing for flexible data management.
+ *
+ * @template DataType - The type of the resource data being managed. Defaults to `any`,
+ * allowing for flexibility in the type of data handled by the provider.
+ *
+ * @template TPrimaryKey - The type of the primary key used to identify resources.
+ *
+ *
+ * ### Methods:
+ *
+ * - **create(record: Partial<DataType>)**: Creates a new resource record.
+ *   - **Parameters**:
+ *     - `record`: The data for the new resource to be created.
+ *   - **Returns**: A promise that resolves to an `DataType`,
+ *     indicating the success or failure of the operation.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.create({ name: "New ResourceMeta" });
+ *     ```
+ *
+ * - **update(primaryKey: TPrimaryKey, updatedData: Partial<DataType>)**: Updates an existing resource record.
+ *   - **Parameters**:
+ *     - `primaryKey`: The primary key of the resource to update.
+ *     - `updatedData`: An object containing the updated data for the resource.
+ *   - **Returns**: A promise that resolves to an `DataType`,
+ *     indicating the success or failure of the update operation.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.update("resourceId", { name: "Updated ResourceMeta" });
+ *     ```
+ *
+ * - **delete(primaryKey: TPrimaryKey)**: Deletes a resource record by its primary key.
+ *   - **Parameters**:
+ *     - `primaryKey`: The primary key of the resource to delete.
+ *     indicating the success or failure of the delete operation.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.delete("resourceId");
+ *     ```
+ *
+ * - **findOne(primaryKey: TPrimaryKey)**: Retrieves a single resource record by its primary key.
+ *   - **Parameters**:
+ *     - `primaryKey`: The primary key of the resource to retrieve.
+ *   - **Returns**: A promise that resolves to an `DataType | null`,
+ *     containing the requested resource record or null if not found.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.findOne("resourceId");
+ *     ```
+ *
+ * - **findOneOrFail(primaryKey: TPrimaryKey)**: Retrieves a single resource record by its primary key or throws an error if not found.
+ *   - **Parameters**:
+ *     - `primaryKey`: The primary key of the resource to retrieve.
+ *   - **Returns**: A promise that resolves to an `DataType`,
+ *     containing the requested resource record.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.findOneOrFail("resourceId");
+ *     ```
+ *
+ * - **find(options?: ResourceQueryOptions<DataType>)**: Retrieves multiple resource records based on query options.
+ *   - **Parameters**:
+ *     - `options`: Optional query options to filter the results.
+ *   - **Returns**: A promise that resolves to an `ResourcePaginatedResult<DataType>`,
+ *     containing the list of resource records.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.find({ limit: 10, skip: 0 });
+ *     ```
+ *
+ * - **findAndCount(options?: ResourceQueryOptions<DataType>)**: Retrieves multiple resource records and the total count based on query options.
+ *   - **Parameters**:
+ *     - `options`: Optional query options to filter the results.
+ *   - **Returns**: A promise that resolves to an `ResourcePaginatedResult<DataType>`,
+ *     containing the list of resource records and the total count.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.findAndCount({ limit: 10, skip: 0 });
+ *     ```
+ *
+ * - **createMany(data: Partial<DataType>[])**: Creates multiple resource records.
+ *   - **Parameters**:
+ *     - `data`: An array of data for the new resources to be created.
+ *   - **Returns**: A promise that resolves to an `DataType[]`,
+ *     indicating the success or failure of the operation.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.createMany([{ name: "ResourceMeta 1" }, { name: "ResourceMeta 2" }]);
+ *     ```
+ *
+ * - **updateMany(data: ResourceManyCriteria<TPrimaryKey,DataType>)**: Updates multiple resource records.
+ *   - **Parameters**:
+ *     - `data`: An object containing the updated data for the resources.
+ *   - **Returns**: A promise that resolves to an `DataType[]`,
+ *     indicating the success or failure of the update operation.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.updateMany({ status: "active" });
+ *     ```
+ *
+ * - **deleteMany(criteria: ResourceQueryOptions<DataType>)**: Deletes multiple resource records based on criteria.
+ *   - **Parameters**:
+ *     - `criteria`: The criteria to filter which resources to delete.
+ *   - **Returns**: A promise that resolves to an `number`,
+ *     indicating the success or failure of the delete operation.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.deleteMany({ filters: { status: "inactive" } });
+ *     ```
+ *
+ * - **count(options?: ResourceQueryOptions<DataType>)**: Counts the total number of resource records based on query options.
+ *   - **Parameters**:
+ *     - `options`: Optional query options to filter the count.
+ *   - **Returns**: A promise that resolves to an `number`,
+ *     containing the total count of resource records.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.count({ filters: { status: "active" } });
+ *     ```
+ *
+ * - **exists(primaryKey: TPrimaryKey)**: Checks if a resource record exists by its primary key.
+ *   - **Parameters**:
+ *     - `primaryKey`: The primary key of the resource to check.
+ *   - **Returns**: A promise that resolves to an `boolean`,
+ *     indicating whether the resource exists.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.exists("resourceId");
+ *     ```
+ *
+ * - **distinct?(field: keyof DataType, options?: ResourceQueryOptions<DataType>)**: Retrieves distinct values for a specified field.
+ *   - **Parameters**:
+ *     - `field`: The field for which to retrieve distinct values.
+ *     - `options`: Optional query options to filter the results.
+ *   - **Returns**: A promise that resolves to an `DataType[]`,
+ *     containing the distinct values.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.distinct("category");
+ *     ```
+ *
+ * - **aggregate?(pipeline: any[])**: Performs aggregation operations on the resource data.
+ *   - **Parameters**:
+ *     - `pipeline`: An array representing the aggregation pipeline.
+ *   - **Returns**: A promise that resolves to an `number`,
+ *     containing the aggregated results.
+ *   - **Example**:
+ *     ```typescript
+ *     const result = await dataProvider.aggregate([{ $group: { _id: "$category", count: { $sum: 1 } } }]);
+ *     ```
+ *
+ * ### Notes:
+ * - This interface provides a standard way to interact with resource data,
+ *   ensuring that all operations return consistent results.
+ * - The use of promises allows for asynchronous operations, making it suitable
+ *   for use in modern web applications.
+ *
+ * ### Example Usage:
+ * Here’s how you might implement the `ResourceDataService` interface:
+ *
+ * ```typescript
+ * class MyDataProvider implements ResourceDataService<MyResourceType> {
+ *     async create(record: MyResourceType) {
+ *         // Implementation for creating a resource
+ *     }
+ *
+ *     async list() {
+ *         // Implementation for fetching resources
+ *     }
+ *
+ *     // Implement other methods...
+ * }
+ * ```
+ *
+ * ### Summary:
+ * The `ResourceDataService` interface defines a comprehensive set of methods
+ * for managing resources, facilitating CRUD operations and ensuring a consistent
+ * approach to data handling in applications.
+ */
+export interface ResourceDataService<DataType = unknown, TPrimaryKey extends ResourcePrimaryKey = ResourcePrimaryKey> {
+    /***
+     * Creates a new resource record.
+     * @template T - The type of the resource data being created.
+     * @param record The data for the new resource to be created.
+     * @returns A promise that resolves to an `DataType`,
+     * indicating the success or failure of the operation.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.create({ name: "New ResourceMeta" });
+     *     ```
+     */
+    create<T extends DataType>(record: T): Promise<DataType>;
+    /***
+     * Updates an existing resource record.
+     * @template T - The type of the resource data being updated.
+     * @param primaryKey The primary key of the resource to update.
+     * @param updateData An object containing the updated data for the resource.
+     * @returns A promise that resolves to an `DataType`,
+     * indicating the success or failure of the update operation.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.update("resourceId", { name: "Updated ResourceMeta" });
+     *     ```
+     */
+    update<T extends Partial<DataType>>(primaryKey: TPrimaryKey, updateData: T): Promise<DataType>;
+    /***
+     * Deletes a resource record by its primary key.
+     * @param primaryKey The primary key of the resource to delete.
+     * @returns A promise that resolves to an `Promise<boolean>`,
+     * indicating the success or failure of the delete operation.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.delete("resourceId");
+     *     ```
+     */
+    delete(primaryKey: TPrimaryKey): Promise<boolean>;
+    /***
+     * Retrieves a single resource record by its primary key.
+     * @param options The primary key or query options of the resource to retrieve.
+     * @returns A promise that resolves to an `DataType | null`,
+     * containing the requested resource record or null if not found.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.findOne("resourceId");
+     *     ```
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.findOne({ firstName: 1 });
+     *     ```
+     */
+    findOne(options: TPrimaryKey | ResourceQueryOptions<DataType>): Promise<DataType | null>;
+    /***
+     * Retrieves a single resource record by its primary key or throws an error if not found.
+     * @param primaryKey The primary key or query options of the resource to retrieve.
+     * @returns A promise that resolves to an `DataType`,
+     * containing the requested resource record.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.findOneOrFail("resourceId");
+     *     ```
+     */
+    findOneOrFail(options: TPrimaryKey | ResourceQueryOptions<DataType>): Promise<DataType>;
+    /***
+     * Retrieves multiple resource records based on query options.
+     * @param options Optional query options to filter the results.
+     * @returns A promise that resolves to an `DataType[]`,
+     * containing the list of resource records.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.find({ limit: 10, skip: 0 });
+     *     ```
+     */
+    find(options?: ResourceQueryOptions<DataType>): Promise<DataType[]>;
+    /***
+     * Retrieves multiple resource records and the total count based on query options.
+     * @param options Optional query options to filter the results.
+     * @returns A promise that resolves to an `DataType[]`,
+     * containing the list of resource records and the total count.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.findAndCount({ limit: 10, skip: 0 });
+     *     ```
+     */
+    findAndCount(options?: ResourceQueryOptions<DataType>): Promise<[DataType[], number]>;
+    /***
+     * Retrieves multiple resource records and paginates the results.
+     * @param options Optional query options to filter the results.
+     * @returns A promise that resolves to an `ResourcePaginatedResult<DataType>`,
+     * containing the list of resource records and the total count.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.findAndPaginate({ limit: 10, skip: 0 });
+     */
+    findAndPaginate(options?: ResourceQueryOptions<DataType>): Promise<ResourcePaginatedResult<DataType>>;
+    /***
+     * Creates multiple resource records.
+     * @template T - The type of the resource data being created.
+     * @param data An array of data for the new resources to be created.
+     * @returns A promise that resolves to an `DataType[]`,
+     * indicating the success or failure of the operation.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.createMany([{ name: "ResourceMeta 1" }, { name: "ResourceMeta 2" }]);
+     *     ```
+     */
+    createMany<T extends DataType>(data: T[]): Promise<DataType[]>;
+    /***
+     * Updates multiple resource records.
+     * @template T - The type of the resource data being updated.
+     * @param criteria An object containing the filter criteria for the resources.
+     * @param data An object containing the updated data for the resources.
+     * @returns A promise that resolves to an `DataType[]`,
+     * indicating the success or failure of the update operation.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.updateMany({ status: "active" });
+     *     ```
+     */
+    updateMany<T extends Partial<DataType>>(criteria: ResourceManyCriteria<DataType, TPrimaryKey>, data: T): Promise<number>;
+    /**
+     *
+     * @param criteria The criteria to filter which resources to delete.
+     * @returns A promise that resolves to an `number`,
+     * indicating the success or failure of the delete operation.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.deleteMany({ filters: { status: "inactive" } });
+     *     ```
+     */
+    deleteMany(criteria: ResourceManyCriteria<DataType, TPrimaryKey>): Promise<number>;
+    /***
+     * Counts the total number of resource records based on query options.
+     * @param options Optional query options to filter the count.
+     * @returns A promise that resolves to an `number`,
+     * containing the total count of resource records.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.count({ filters: { status: "active" } });
+     *     ```
+     */
+    count(options?: ResourceQueryOptions<DataType>): Promise<number>;
+    /**
+     *
+     * @param primaryKey The primary key of the resource to check.
+     * @returns A promise that resolves to an `boolean`,
+     * indicating whether the resource exists.
+     * @example
+     *   ```typescript
+     *   const result = await dataProvider.exists("resourceId");
+     *     ```
+     */
+    exists(primaryKey: TPrimaryKey): Promise<boolean>;
+}
+/**
+ * @type ResourceManyCriteria
+ *
+ * Represents the criteria used for  multiple actions on a resource.
+ * This type allows for flexible definitions of what constitutes an update,
+ * accommodating various scenarios based on the primary key or partial data.
+ *
+ * ### Type Parameters
+ * - **TPrimaryKey**: The type of the primary key used to identify resources.
+ *   Defaults to `ResourcePrimaryKey`, which can be a string, number, or object.
+ * - **DataType**: The type of data associated with the resource. Defaults to `Dictionary`,
+ *   which is a generic dictionary type allowing for any key-value pairs.
+ *
+ * ### Possible Forms
+ * The `ResourceManyCriteria` can take one of the following forms:
+ *
+ * 1. **Array of Primary Keys**:
+ *    - An array of primary keys that uniquely identify the resources to be updated.
+ *    - **Example**:
+ *      ```typescript
+ *      const updateCriteria: ResourceManyCriteria<string> = ["user123", "user456"];
+ *      ```
+ *
+ * 2. **Partial Data Object**:
+ *    - An object containing partial data that represents the fields to be updated.
+ *    - **Example**:
+ *      ```typescript
+ *      const updateCriteria: ResourceManyCriteria<string, { name: string; age: number }> = {
+ *          name: "John Doe",
+ *          age: 30
+ *      };
+ *      ```
+ *
+ * 3. **Record of Data Fields**:
+ *    - A record where each key corresponds to a field in the resource, allowing for
+ *      updates to specific fields.
+ *    - **Example**:
+ *      ```typescript
+ *      const updateCriteria: ResourceManyCriteria<string, { name: string; age: number }> = {
+ *          name: "Jane Doe",
+ *          age: 25
+ *      };
+ *      ```
+ *
+ * ### Notes
+ * - This type is particularly useful in scenarios where resources can be updated
+ *   based on different criteria, such as updating multiple records at once or
+ *   modifying specific fields of a resource.
+ * - By leveraging TypeScript's generics, this type provides strong typing and
+ *   flexibility, ensuring that the criteria used for updates are well-defined and
+ *   type-safe.
+ *
+ * ### Example Usage
+ * Here’s how you might use the `ResourceManyCriteria` type in a function that
+ * updates resources:
+ *
+ * ```typescript
+ * function updateResources(criteria: ResourceManyCriteria<string, { name: string; age: number }>) {
+ *     // Implementation to update resources based on the provided criteria
+ * }
+ *
+ * // Example of updating resources by primary keys
+ * updateResources(["user123", "user456"]);
+ *
+ * // Example of updating resources with partial data
+ * updateResources({ name: "John Doe", age: 30 });
+ * ```
+ * @typeParam DataType - The type of data associated with the resource.
+ * @default any
+ * @typeParam TPrimaryKey - The type of the primary key used to identify resources.
+ * @default ResourcePrimaryKey
+ * @see {@link ResourcePrimaryKey} for the `ResourcePrimaryKey` type.
+ * @see {@link MongoQuery} for the `MongoQuery` type.
+ * @example
+ * // Example of using ResourceManyCriteria
+ * const criteria: ResourceManyCriteria<string, { name: string; age: number }> = {
+ *   name: "John Doe",
+ *   age: 30
+ * };
+ * @Example
+ * // Example of using ResourceManyCriteria with an array of primary keys
+ * const criteria: ResourceManyCriteria<string, { name: string; age: number }> = [
+ *   "user123",
+ *   "user456"
+ * ];
+ */
+export type ResourceManyCriteria<DataType = unknown, TPrimaryKey extends ResourcePrimaryKey = ResourcePrimaryKey> = TPrimaryKey[] | MongoQuery<DataType>;
+/**
+ * Interface representing options for fetching resources.
+ *
+ * This interface allows you to specify various options when retrieving resources,
+ * including filters to narrow down the results based on specific criteria.
+ *
+ * @template DataType - The type of data being fetched. Defaults to 'any'.
+ * @example
+ * // Example of using ResourceQueryOptions
+ * const fetchOptions: ResourceQueryOptions<MyDataType, string> = {
+ *     filters: {
+ *             status: { $eq: "active" }, // Filter for active resources
+ *             category: { $in: ["A", "B"] } // Filter for categories A or B
+ *      },
+ *      orderBy: { createdAt: 'desc' }, // Sort by creation date descending
+ *      limit: 20, // Limit results to 20
+ *      skip: 0 // Do not skip any results
+ * };
+ */
+export interface ResourceQueryOptions<DataType = unknown> {
+    /** Fields to include in the response. */
+    fields?: Array<keyof DataType extends never ? string : keyof DataType>;
+    relations?: string[];
+    orderBy?: ResourceQueryOrderBy<DataType>;
+    limit?: number;
+    skip?: number;
+    page?: number;
+    /** Include relationships or nested resources. */
+    include?: ResourceName[];
+    /** Include only distinct results or specific fields for distinct values. */
+    distinct?: boolean | Array<keyof DataType>;
+    /** Include soft-deleted resources. */
+    includeDeleted?: boolean;
+    /** Cache the results for performance optimization. */
+    cache?: boolean;
+    /** Time-to-Live for cache, in seconds. */
+    cacheTTL?: number;
+    /**
+     * Where clause to filter the results.
+     * Resources are filtered using a MongoDB-like query syntax.
+     * This allows you to specify conditions for filtering resources based on various criteria.
+     *
+     * @type {MongoQuery}
+     * @see {@link https://www.mongodb.com/docs/manual/reference/operator/query/} for more information on MongoDB query operators.
+     * @example
+     * const queryOptions: ResourceQueryOptions<{ id: number, name: string }> = {
+     *   where: {
+     *     name : "John",
+     *     surname : "Doe"
+     *   },
+     *   orderBy: { name: 'asc' },
+     *   limit: 10,
+     *   skip: 0
+     * };
+     * @see {@link MongoQuery} for more information on where clauses.
+     * @example
+     * const queryOptions: ResourceQueryOptions<{ id: number, name: string }> = {
+     *   where: {
+     *     name : "John",
+     *     surname : "Doe"
+     *   },
+     *   orderBy: { name: 'asc' },
+     *   limit: 10,
+     *   skip: 0
+     * };
+     */
+    where?: MongoQuery<DataType>;
+}
+/**
+ * @interface ResourcePaginatedResult
+ *
+ * Represents the result of a paginated resource list operation.
+ * This interface encapsulates the data retrieved from a paginated API response,
+ * along with metadata about the pagination state and navigation links.
+ *
+ * @template DataType - The type of the resources being fetched. Defaults to `any`.
+ *
+ * ### Properties:
+ *
+ * - **data**: An array of fetched resources.
+ *   - **Type**: `DataType[]`
+ *   - **Description**: This property contains the list of resources retrieved from the API.
+ *   - **Example**:
+ *     ```typescript
+ *     const result: ResourcePaginatedResult<User> = {
+ *         data: [
+ *             { id: 1, name: "John Doe" },
+ *             { id: 2, name: "Jane Smith" }
+ *         ],
+ *         meta: { totalItems: 100, currentPage: 1, pageSize: 10, totalPages: 10 },
+ *         links: { first: null, previous: null, next: "http://api.example.com/users?page=2", last: "http://api.example.com/users?page=10" }
+ *     };
+ *     ```
+ *
+ * - **meta**: Metadata about the pagination state.
+ *   - **Type**: `Object`
+ *   - **Description**: This property provides information about the total number of items, the current page, the page size, and the total number of pages.
+ *   - **Properties**:
+ *     - **totalItems**: The total number of items available across all pages.
+ *       - **Type**: `number`
+ *       - **Example**: `100` indicates there are 100 items in total.
+ *     - **currentPage**: The current page number being viewed.
+ *       - **Type**: `number`
+ *       - **Example**: `1` indicates the first page.
+ *     - **pageSize**: The number of items displayed per page.
+ *       - **Type**: `number`
+ *       - **Example**: `10` indicates that 10 items are shown per page.
+ *     - **totalPages**: The total number of pages available.
+ *       - **Type**: `number`
+ *       - **Example**: `10` indicates there are 10 pages in total.
+ *
+ * - **links**: Navigation links for paginated results.
+ *   - **Type**: `Object`
+ *   - **Description**: This property contains URLs for navigating through the paginated results.
+ *   - **Properties**:
+ *     - **first**: URL to the first page of results.
+ *       - **Type**: `string | null`
+ *       - **Example**: `"http://api.example.com/users?page=1"` or `null` if there is no first page.
+ *     - **previous**: URL to the previous page of results.
+ *       - **Type**: `string | null`
+ *       - **Example**: `"http://api.example.com/users?page=1"` or `null` if there is no previous page.
+ *     - **next**: URL to the next page of results.
+ *       - **Type**: `string | null`
+ *       - **Example**: `"http://api.example.com/users?page=2"` or `null` if there is no next page.
+ *     - **last**: URL to the last page of results.
+ *       - **Type**: `string | null`
+ *       - **Example**: `"http://api.example.com/users?page=10"` or `null` if there is no last page.
+ *
+ * ### Example Usage:
+ * Here’s how you might use the `ResourcePaginatedResult` interface in a function that fetches paginated user data:
+ *
+ * ```typescript
+ * async function fetchUsers(page: number): Promise<ResourcePaginatedResult<User>> {
+ *     const response = await list(`http://api.example.com/users?page=${page}`);
+ *     const result: ResourcePaginatedResult<User> = await response.json();
+ *     return result;
+ * }
+ *
+ * fetchUsers(1).then(result => {
+ *     console.log(`Total Users: ${result.meta.totalItems}`);
+ *     console.log(`Current Page: ${result.meta.currentPage}`);
+ *     console.log(`Users on this page:`, result.data);
+ * });
+ * ```
+ *
+ * ### Notes:
+ * - This interface is particularly useful for APIs that return large datasets,
+ *   allowing clients to retrieve data in manageable chunks.
+ * - The `links` property facilitates easy navigation between pages, enhancing user experience.
+ */
+export interface ResourcePaginatedResult<DataType = unknown> {
+    /** List of fetched resources. */
+    data: DataType[];
+    statusCode?: number;
+    success?: boolean;
+    error?: any;
+    message?: string;
+    status?: string;
+    errors?: string | Error[];
+    /** Pagination metadata. */
+    meta?: ResourcePaginationMeta;
+    /** Links for navigation in paginated results. */
+    links?: {
+        /** URL or index to the first page. */
+        first?: string | number;
+        /** URL or index to the previous page. */
+        previous?: string | number;
+        /** URL or index to the next page. */
+        next?: string | number;
+        /** URL or index to the last page. */
+        last?: string | number;
+    };
+}
+/**
+ * @typedef ResourcePaginationMeta
+ * Represents the pagination metadata for a resource.
+ *
+ * This type defines the structure of the pagination metadata returned by a resource query operation.
+ * It includes information about the total number of items, the current page, the page size, and other
+ * pagination-related properties.
+ *
+ * @property {number} total - The total number of items available.
+ * @property {number} [currentPage] - The current page number.
+ * @property {number} [pageSize] - The number of items per page.
+ * @property {number} [totalPages] - The total number of pages.
+ * @property {number} [nextPage] - The next page number.
+ * @property {number} [previousPage] - The previous page number.
+ * @property {number} [lastPage] - The last page number.
+ * @property {boolean} [hasNextPage] - Whether there is a next page.
+ * @property {boolean} [hasPreviousPage] - Whether there is a previous page.
+ */
+export interface ResourcePaginationMeta {
+    /** The total number of items available. */
+    total: number;
+    /** The current page number. */
+    currentPage?: number;
+    /** The number of items per page. */
+    pageSize?: number;
+    /** The total number of pages. */
+    totalPages?: number;
+    nextPage?: number;
+    previousPage?: number;
+    lastPage?: number;
+    /***
+     * Whether there is a next page.
+     */
+    hasNextPage?: boolean;
+    /***
+     * Whether there is a previous page.
+     */
+    hasPreviousPage?: boolean;
+}
+/**
+ * Type representing default events that can occur on a resource.
+ * This includes both action names and data service method names.
+ *
+ * This type combines resource-specific action names with standard data service
+ * operations to provide a comprehensive set of events that can be tracked or
+ * handled for a given resource. It's useful for event-driven architectures,
+ * logging, auditing, and reactive systems.
+ *
+ * @type ResourceDefaultEvent
+ * @template TResourceName - The name of the resource
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - event type for a specific resource
+ * import "reslib/resources";
+ *
+ * declare module "reslib/resources" {
+ *   interface Resources {
+ *     users: {
+ *       actions: {
+ *         read: { label: "Read User" };
+ *         create: { label: "Create User" };
+ *         update: { label: "Update User" };
+ *         archive: { label: "Archive User" };
+ *       }
+ *     };
+ *   }
+ * }
+ *
+ * // All possible events for the users resource
+ * type UserEvent = ResourceDefaultEvent<"users">;
+ * // Result: "read" | "create" | "update" | "archive" | "create" | "update" | "delete" | "findOne" | "find" | ...
+ *
+ * // Note: Includes both resource actions and data service methods
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Event-driven resource management
+ * class ResourceEventEmitter<TResourceName extends ResourceName> {
+ *   private listeners = new Map<ResourceDefaultEvent<TResourceName>, Function[]>();
+ *
+ *   on(event: ResourceDefaultEvent<TResourceName>, listener: Function) {
+ *     const current = this.listeners.get(event) || [];
+ *     current.push(listener);
+ *     this.listeners.set(event, current);
+ *   }
+ *
+ *   emit(event: ResourceDefaultEvent<TResourceName>, data?: any) {
+ *     const listeners = this.listeners.get(event) || [];
+ *     listeners.forEach(listener => listener(data));
+ *   }
+ * }
+ *
+ * // Usage
+ * const userEmitter = new ResourceEventEmitter<"users">();
+ *
+ * userEmitter.on("create", (userData) => {
+ *   console.log("User created:", userData);
+ *   // Send welcome email, update analytics, etc.
+ * });
+ *
+ * userEmitter.on("findOne", (userId) => {
+ *   console.log("User accessed:", userId);
+ *   // Log access, update last accessed time, etc.
+ * });
+ *
+ * // Trigger events
+ * userEmitter.emit("create", { id: 1, name: "John" });
+ * userEmitter.emit("findOne", 1);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Audit logging with typed events
+ * interface AuditLog<TResourceName extends ResourceName> {
+ *   resource: TResourceName;
+ *   event: ResourceDefaultEvent<TResourceName>;
+ *   userId: string;
+ *   timestamp: Date;
+ *   data?: any;
+ * }
+ *
+ * class ResourceAuditor {
+ *   private logs: AuditLog<ResourceName>[] = [];
+ *
+ *   log<TResourceName extends ResourceName>(
+ *     resource: TResourceName,
+ *     event: ResourceDefaultEvent<TResourceName>,
+ *     userId: string,
+ *     data?: any
+ *   ) {
+ *     this.logs.push({
+ *       resource,
+ *       event,
+ *       userId,
+ *       timestamp: new Date(),
+ *       data
+ *     });
+ *   }
+ *
+ *   getLogsForResource<TResourceName extends ResourceName>(
+ *     resource: TResourceName
+ *   ): AuditLog<TResourceName>[] {
+ *     return this.logs.filter(log => log.resource === resource) as AuditLog<TResourceName>[];
+ *   }
+ * }
+ *
+ * // Usage
+ * const auditor = new ResourceAuditor();
+ *
+ * auditor.log("users", "create", "user123", { name: "John Doe" });
+ * auditor.log("users", "update", "user456", { id: 1, name: "Jane Doe" });
+ * auditor.log("users", "find", "user789"); // Data service method
+ *
+ * const userLogs = auditor.getLogsForResource("users");
+ * // TypeScript knows these are user-related events
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Reactive resource hooks
+ * function useResourceEvent<TResourceName extends ResourceName>(
+ *   resource: TResourceName,
+ *   event: ResourceDefaultEvent<TResourceName>,
+ *   callback: (data?: any) => void
+ * ) {
+ *   // Implementation would set up event listeners
+ *   console.log(`Setting up ${event} listener for ${resource}`);
+ *   // Return cleanup function, etc.
+ * }
+ *
+ * // Usage in a React-like component
+ * function UserComponent() {
+ *   // Type-safe event handling
+ *   useResourceEvent("users", "create", (userData) => {
+ *     console.log("New user created:", userData);
+ *     // Update UI, refresh data, etc.
+ *   });
+ *
+ *   useResourceEvent("users", "update", (updateData) => {
+ *     console.log("User updated:", updateData);
+ *     // Refresh user data, show notification, etc.
+ *   });
+ *
+ *   useResourceEvent("users", "findOne", (userId) => {
+ *     console.log("User profile viewed:", userId);
+ *     // Track analytics, etc.
+ *   });
+ *
+ *   return <div>User Management Component</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Middleware system with typed events
+ * type MiddlewareFn<TResourceName extends ResourceName> = (
+ *   event: ResourceDefaultEvent<TResourceName>,
+ *   data: any,
+ *   next: () => void
+ * ) => void;
+ *
+ * class ResourceMiddleware<TResourceName extends ResourceName> {
+ *   private middlewares: MiddlewareFn<TResourceName>[] = [];
+ *
+ *   use(middleware: MiddlewareFn<TResourceName>) {
+ *     this.middlewares.push(middleware);
+ *   }
+ *
+ *   async execute(event: ResourceDefaultEvent<TResourceName>, data: any) {
+ *     let index = 0;
+ *
+ *     const next = () => {
+ *       if (index < this.middlewares.length) {
+ *         this.middlewares[index++](event, data, next);
+ *       }
+ *     };
+ *
+ *     next();
+ *   }
+ * }
+ *
+ * // Usage
+ * const userMiddleware = new ResourceMiddleware<"users">();
+ *
+ * userMiddleware.use((event, data, next) => {
+ *   console.log(`Pre-${event} validation`);
+ *   // Validate permissions, data, etc.
+ *   next();
+ * });
+ *
+ * userMiddleware.use((event, data, next) => {
+ *   console.log(`Post-${event} logging`);
+ *   // Log the event, send notifications, etc.
+ *   next();
+ * });
+ *
+ * // Execute middleware for events
+ * userMiddleware.execute("create", { name: "John" });
+ * userMiddleware.execute("findOne", 123);
+ * ```
+ */
+export type ResourceDefaultEvent<TResourceName extends ResourceName> = ResourceActionName<TResourceName> | keyof ResourceDataService;
+/**
+ * Represents contextual information about a resource for operations like translations, logging, and error handling.
+ *
+ * This interface provides a standardized way to pass resource identification and contextual data
+ * throughout the application. It's primarily used for internationalization, error messages, and
+ * logging where resource-specific information is needed.
+ *
+ * @interface ResourceContext
+ *
+ * @example
+ * ```typescript
+ * // Basic usage in translations
+ * const context: ResourceContext = {
+ *   resourceName: "user",
+ *   resourceLabel: "User",
+ *   operation: "create",
+ *   count: 5
+ * };
+ *
+ * // Used in error messages
+ * i18n.t("resources.notFound", context);
+ * // Results in: "User with ID 123 not found"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Extended with custom properties
+ * const extendedContext: ResourceContext = {
+ *   resourceName: "product",
+ *   resourceLabel: "Product",
+ *   category: "electronics",
+ *   price: 99.99
+ * };
+ * ```
+ */
+export interface ResourceContext extends Record<string, any> {
+    /** The unique programmatic name of the resource */
+    resourceName: ResourceName;
+    /** The human-readable label of the resource for display purposes */
+    resourceLabel: string;
+}
+/**
+ * @interface ResourceTranslations
+ *
+ * Represents the translation structure for resources in the application.
+ * This type defines the expected structure of translations for each resource,
+ * including labels, titles, and action-specific translations.
+ *
+ * @example
+ * ```typescript
+ * // resources actions translations structure :
+ * // Here is an example of the structure of the translations for the "user" resource:
+ * const userTranslations: ResourceTranslations = {
+ *   user: {
+ *     label: "User",
+ *     title: "Manage user data",
+ *     create: {
+ *       label: "Create User",
+ *       title: "Click to add a new user.",
+ *     },
+ *     read: {
+ *       label: "View User",
+ *       title: "Click to view a specific user.",
+ *     },
+ *     update: {
+ *       label: "Update User",
+ *       title: "Click to update a specific user.",
+ *       zero: "No users to update.",
+ *       one: "Updated one user.",
+ *       other: "Updated %{count} users.",
+ *     },
+ *     delete: {
+ *       label: "Delete User",
+ *       title: "Click to delete a specific user.",
+ *       zero: "No users to delete.",
+ *       one: "Deleted one user.",
+ *       other: "Deleted %{count} users.",
+ *     },
+ *   }
+ * };
+ * ```
+ */
+export type ResourceTranslations = {
+    [Name in ResourceName]: ResourceTranslation<Name>;
+}[ResourceName];
+/**
+ * @interface ResourceTranslation
+ *
+ * Represents the translation structure for a specific resource in the application.
+ * This generic type defines the expected structure of translations for a given resource,
+ * dynamically generating the translation keys based on the resource's defined actions.
+ *
+ * @template Name - The name of the resource for which translations are defined.
+ * Must be a valid `ResourceName`.
+ *
+ * ### Structure:
+ *
+ * - **Core Properties**:
+ *   - `label`: The display name of the resource (required).
+ *   - `title`: The title or heading for the resource (optional).
+ *   - `description`: A detailed description of the resource (optional).
+ *   - `forbiddenError`: Error message when access to the resource is forbidden (required).
+ *   - `notFoundError`: Error message when the resource is not found (required).
+ *
+ * - **Action Translations**: Dynamically generated based on the resource's actions.
+ *   Each action defined in the resource's `actions` property will have:
+ *   - `label`: The display label for the action.
+ *   - `title`: The tooltip or help text for the action.
+ *   - `zero`: Message when no items are affected (for pluralization).
+ *   - `one`: Message when one item is affected (for pluralization).
+ *   - `other`: Message when multiple items are affected (for pluralization).
+ *
+ * - **Additional Properties**: Any additional translation keys can be added via `Record<string, any>`.
+ *
+ * ### Type Generation:
+ *
+ * The type uses conditional types and mapped types to dynamically generate the structure:
+ * - It checks if the resource has an `actions` property.
+ * - For each action, it creates a translation object with the required fields.
+ * - It combines this with the core properties and allows for additional custom properties.
+ *
+ * @example
+ * ```typescript
+ * // For a resource with actions: { read: {...}, create: {...}, update: {...}, delete: {...} }
+ * const userTranslations: ResourceTranslation<"user"> = {
+ *   label: "User",
+ *   title: "Manage user data",
+ *   description: "User management and administration",
+ *   forbiddenError: "You do not have permission to access this resource.",
+ *   notFoundError: "The requested user was not found.",
+ *
+ *   // Action-specific translations (auto-generated based on resource actions)
+ *   read: {
+ *     label: "View User",
+ *     title: "Click to view a specific user.",
+ *     zero: "No users found.",
+ *     one: "Viewing one user.",
+ *     other: "Viewing %{count} users."
+ *   },
+ *   create: {
+ *     label: "Create User",
+ *     title: "Click to add a new user.",
+ *     zero: "No users created.",
+ *     one: "Created one user.",
+ *     other: "Created %{count} users."
+ *   },
+ *   update: {
+ *     label: "Update User",
+ *     title: "Click to update a specific user.",
+ *     zero: "No users updated.",
+ *     one: "Updated one user.",
+ *     other: "Updated %{count} users."
+ *   },
+ *   delete: {
+ *     label: "Delete User",
+ *     title: "Click to delete a specific user.",
+ *     zero: "No users deleted.",
+ *     one: "Deleted one user.",
+ *     other: "Deleted %{count} users."
+ *   },
+ *
+ *   // Additional custom translations
+ *   customAction: "Custom action performed",
+ *   validationError: "Please check your input"
+ * };
+ * ```
+ *
+ * ### Notes:
+ *
+ * - The action translations are automatically inferred from the resource's action definitions.
+ * - The `zero`, `one`, and `other` fields support pluralization in internationalization.
+ * - The `%{count}` placeholder can be used in pluralization messages for dynamic counts.
+ * - Additional properties allow for custom translations specific to the resource's needs.
+ * - This type ensures type safety by tying translations directly to the resource structure.
+ */
+export type ResourceTranslation<Name extends ResourceName> = {
+    /**
+     * The display name of the resource (required).
+     */
+    label: string;
+    /**
+     * The title or heading for the resource (optional).
+     */
+    title?: string;
+    /**
+     * A detailed description of the resource (optional).
+     */
+    description?: string;
+    /**
+     * Error message when access to the resource is forbidden (required).
+     */
+    forbiddenError: string;
+    /**
+     * Error message when the resource is not found (required).
+     */
+    notFoundError: string;
+} & (Resources[Name] extends {
+    actions: infer Actions;
+} ? Actions extends Record<string, ResourceAction> ? {
+    [Key in keyof Actions]: {
+        /**
+         * The display label for the action.
+         */
+        label?: string;
+        /**
+         * The tooltip or help text for the action.
+         */
+        title?: string;
+        /**
+         * Message when no items are affected (for pluralization).
+         */
+        zero?: string;
+        /**
+         * Message when one item is affected (for pluralization).
+         */
+        one?: string;
+        /**
+         * Message when multiple items are affected (for pluralization).
+         */
+        other?: string;
+    };
+}[keyof Actions] : {} : {}) & Dictionary;