@plyaz/types 1.6.0 → 1.7.0

package/dist/common/types.d.ts

@@ -12,11 +12,1573 @@
  * // getUser("abc") // ❌ Type error
  * ```
  */
-export type Brand<T, B> = T & {
-    readonly _brand: B;
-};
+import type { Arrayable, SetOptional, Tagged, UnknownRecord } from 'type-fest';
+export type Brand<T, B extends PropertyKey> = Tagged<T, B>;
 /**
  * Branded `string` type representing a unique identifier.
  * @description This is used to avoid mixing generic strings with semantically significant IDs in function arguments and data structures.
  */
 export type ID = Brand<string, 'ID'>;
+/**
+ * Base interface for entities with timestamps.
+ * Provides common timestamp fields for tracking creation and modification times.
+ *
+ * @example
+ * ```typescript
+ * interface User extends Timestamped {
+ *   id: string;
+ *   name: string;
+ * }
+ * ```
+ */
+export interface Timestamped<CreatedAt = Date, UpdatedAt = Date> {
+    /** When the entity was created */
+    createdAt: CreatedAt;
+    /** When the entity was last updated */
+    updatedAt: UpdatedAt;
+}
+/**
+ * Base interface for entities with an identifier.
+ * Provides a common id field for uniquely identifying entities.
+ *
+ * @typeParam T - Type of the identifier (string or number)
+ *
+ * @example
+ * ```typescript
+ * interface Product extends Identifiable {
+ *   name: string;
+ *   price: number;
+ * }
+ *
+ * interface LegacyProduct extends Identifiable<number> {
+ *   name: string;
+ * }
+ * ```
+ */
+export interface Identifiable<T = string> {
+    /** Unique identifier for the entity */
+    id: T;
+}
+/**
+ * Base interface for entities with both identifier and timestamps.
+ * Combines Identifiable and Timestamped for complete entity tracking.
+ *
+ * @example
+ * ```typescript
+ * interface Order extends Entity {
+ *   total: number;
+ *   status: OrderStatus;
+ * }
+ * ```
+ */
+export interface Entity extends Identifiable, Timestamped {
+}
+/**
+ * Base interface for loading states.
+ * Provides common fields for tracking async operation states.
+ *
+ * @example
+ * ```typescript
+ * interface DataState<T> extends Loadable {
+ *   data?: T;
+ * }
+ * ```
+ */
+export interface Loadable {
+    /** Whether the operation is currently loading */
+    isLoading: boolean;
+    /** Error that occurred during the operation, if any */
+    error: Error | null;
+}
+/**
+ * Base interface for async data states.
+ * Combines loading state with data result.
+ *
+ * @template T - The type of data being loaded
+ *
+ * @example
+ * ```typescript
+ * const userState: AsyncState<User> = {
+ *   data: user,
+ *   isLoading: false,
+ *   error: null
+ * };
+ * ```
+ */
+export interface AsyncState<T> extends Loadable {
+    /** The loaded data, if available */
+    data: T | undefined;
+}
+/**
+ * Base interface for collections with items.
+ * Provides items array wrapper for collections.
+ *
+ * @typeParam T - Type of items in the collection
+ * @example
+ * ```typescript
+ * interface SearchResults<T> extends WithItems<T> {
+ *   query: string;
+ * }
+ * ```
+ */
+export interface WithItems<T> {
+    /** Array of items in the collection */
+    items: T[];
+}
+/**
+ * Base interface for pagination metadata.
+ * Provides core pagination information without items.
+ *
+ * @example
+ * ```typescript
+ * interface ApiPaginationInfo extends PaginationMetadata {
+ *   // Additional API-specific fields
+ * }
+ * ```
+ */
+export interface PaginationMetadata {
+    /** Total number of items across all pages */
+    total: number;
+    /** Current page number (1-based) */
+    page: number;
+    /** Number of items per page */
+    pageSize: number;
+    /** Total number of pages */
+    totalPages: number;
+}
+/**
+ * Base interface for paginated collection results.
+ * Combines pagination metadata with items array.
+ * Note: This is different from API's Paginated interface which only contains items.
+ *
+ * @example
+ * ```typescript
+ * interface UserList extends PaginatedCollection<User> {
+ *   filters?: UserFilters;
+ * }
+ * ```
+ */
+export interface PaginatedCollection<T> extends PaginationMetadata, WithItems<T> {
+}
+/**
+ * Extended pagination metadata with navigation helpers.
+ * Adds navigation flags to the base pagination metadata.
+ *
+ * @example
+ * ```typescript
+ * interface ApiPaginationInfo extends NavigablePaginationMetadata {
+ *   // Maps hasNext to hasNextPage for API conventions
+ * }
+ * ```
+ */
+export interface NavigablePaginationMetadata extends PaginationMetadata {
+    /** Whether there's a next page */
+    hasNext: boolean;
+    /** Whether there's a previous page */
+    hasPrevious: boolean;
+}
+/**
+ * Extended paginated collection with navigation helpers.
+ * Combines navigation metadata with items array.
+ *
+ * @example
+ * ```typescript
+ * interface SearchResults extends NavigablePaginatedCollection<Result> {
+ *   query: string;
+ * }
+ * ```
+ */
+export interface NavigablePaginatedCollection<T> extends PaginatedCollection<T>, NavigablePaginationMetadata {
+}
+/**
+ * Base interface for soft-deletable entities.
+ * Adds deletion timestamp for soft delete functionality.
+ *
+ * @example
+ * ```typescript
+ * interface Document extends Entity, SoftDeletable {
+ *   content: string;
+ * }
+ * ```
+ */
+export interface SoftDeletable {
+    /** When the entity was soft deleted */
+    deletedAt: Date | null;
+}
+/**
+ * Base interface for named entities.
+ * Provides a common name field.
+ *
+ * @example
+ * ```typescript
+ * interface Category extends Named {
+ *   parentId?: string;
+ * }
+ * ```
+ */
+export interface Named {
+    /** Name of the entity */
+    name: string;
+}
+/**
+ * Base interface for describable entities.
+ * Provides name and description fields.
+ *
+ * @example
+ * ```typescript
+ * interface Project extends Describable {
+ *   status: ProjectStatus;
+ * }
+ * ```
+ */
+export interface Describable extends Named {
+    /** Description of the entity */
+    description: string;
+}
+/**
+ * Base interface for entities with metadata.
+ * Provides metadata field for extensibility.
+ *
+ * @typeParam T - Type of the metadata object, defaults to UnknownRecord
+ *
+ * @example
+ * ```typescript
+ * interface Event extends WithMetadata {
+ *   type: EventType;
+ *   payload: unknown;
+ * }
+ *
+ * interface CustomEvent extends WithMetadata<{ userId: string; sessionId: string }> {
+ *   type: EventType;
+ * }
+ * ```
+ */
+export interface WithMetadata<T = UnknownRecord> {
+    /** Metadata for additional information */
+    metadata: T;
+}
+/**
+ * Base interface for configuration objects.
+ * Provides common configuration fields.
+ *
+ * @example
+ * ```typescript
+ * interface CacheConfig extends Configurable {
+ *   ttl: number;
+ *   strategy: 'memory' | 'redis';
+ * }
+ * ```
+ */
+export interface Configurable {
+    /** Whether this configuration is enabled */
+    isEnabled: boolean;
+}
+/**
+ * Base interface for entities that can be enabled/disabled.
+ * Provides a flag for controlling feature availability.
+ *
+ * @example
+ * ```typescript
+ * interface Feature extends Enabled {
+ *   name: string;
+ *   config: FeatureConfig;
+ * }
+ * ```
+ */
+export interface Enabled {
+    /** Whether this entity is enabled */
+    isEnabled: boolean;
+}
+/**
+ * Base interface for pageable collections.
+ * Provides pagination parameters for list operations.
+ *
+ * @example
+ * ```typescript
+ * interface UserListRequest extends Pageable {
+ *   filters?: UserFilters;
+ * }
+ * ```
+ */
+export interface Pageable {
+    /** Page number to retrieve (starting from 1) */
+    page: number;
+    /** Maximum number of items per page */
+    limit: number;
+}
+/**
+ * Base interface for entities with expiration.
+ * Provides expiration tracking for temporary entities.
+ *
+ * @example
+ * ```typescript
+ * interface Token extends WithExpiration {
+ *   value: string;
+ *   scope: string[];
+ * }
+ * ```
+ */
+export interface WithExpiration<T = Date | string> {
+    /** When the entity expires */
+    expiresAt: T;
+}
+/**
+ * Base interface for resettable entities.
+ * Provides reset functionality.
+ *
+ * @example
+ * ```typescript
+ * interface Counter extends Resettable {
+ *   value: number;
+ *   increment: () => void;
+ * }
+ * ```
+ */
+export interface Resettable {
+    /** Reset to initial state */
+    reset: () => void;
+}
+/**
+ * Base interface for clearable entities.
+ * Provides clear functionality.
+ *
+ * @example
+ * ```typescript
+ * interface Cache extends Clearable {
+ *   size: number;
+ *   get: (key: string) => unknown;
+ * }
+ * ```
+ */
+export interface Clearable {
+    /** Clear all data */
+    clear: () => void;
+}
+/**
+ * Base interface for entities with lifecycle methods.
+ * Provides start, stop, and optional pause/resume functionality.
+ *
+ * @example
+ * ```typescript
+ * interface Service extends WithLifecycle {
+ *   isRunning: boolean;
+ * }
+ * ```
+ */
+export interface WithLifecycle {
+    /** Start the entity */
+    start: () => void | Promise<void>;
+    /** Stop the entity */
+    stop: () => void | Promise<void>;
+    /** Pause the entity (optional) */
+    pause?: () => void | Promise<void>;
+    /** Resume the entity (optional) */
+    resume?: () => void | Promise<void>;
+}
+/**
+ * Base interface for entities with payload.
+ * Provides payload field for events, messages, and requests.
+ *
+ * @typeParam T - Type of the payload data
+ *
+ * @example
+ * ```typescript
+ * interface Message<T> extends WithPayload<T> {
+ *   id: string;
+ *   timestamp: Date;
+ * }
+ * ```
+ */
+export interface WithPayload<T = unknown> {
+    /** Payload data */
+    payload: T;
+}
+/**
+ * Base interface for entities with a value.
+ * Provides value field for settings, flags, and state containers.
+ *
+ * @typeParam T - Type of the value
+ *
+ * @example
+ * ```typescript
+ * interface Setting<T> extends WithValue<T> {
+ *   key: string;
+ *   updatedAt: Date;
+ * }
+ * ```
+ */
+export interface WithValue<T = unknown> {
+    /** The value */
+    value: T;
+}
+/**
+ * Base interface for entities with impact level.
+ * Provides impact field for violations, issues, and assessments.
+ *
+ * @example
+ * ```typescript
+ * interface SecurityIssue extends WithImpact {
+ *   vulnerability: string;
+ *   affectedFiles: string[];
+ * }
+ * ```
+ */
+export interface WithImpact<T = 'minor' | 'moderate' | 'serious' | 'critical'> {
+    /** Impact level or severity */
+    impact: T;
+}
+/**
+ * Base interface for entities with an element reference.
+ * Provides element field for UI interactions and DOM manipulation.
+ *
+ * @typeParam T - Type of the element, defaults to HTMLElement
+ *
+ * @example
+ * ```typescript
+ * interface DragOperation extends WithElement {
+ *   startPosition: { x: number; y: number };
+ * }
+ * ```
+ */
+export interface WithElement<T = HTMLElement> {
+    /** The element reference */
+    element: T;
+}
+/**
+ * Base interface for interval/timer controls.
+ * Provides common methods for managing timed operations.
+ *
+ * @example
+ * ```typescript
+ * interface AnimationLoop extends IntervalControl {
+ *   frameRate: number;
+ * }
+ * ```
+ */
+export interface IntervalControl {
+    /** Start the interval */
+    start: () => void;
+    /** Stop the interval */
+    stop: () => void;
+    /** Check if currently running */
+    isRunning: () => boolean;
+    /** Pause the interval (optional) */
+    pause?: () => void;
+    /** Resume from pause (optional) */
+    resume?: () => void;
+    /** Check if currently paused (optional) */
+    isPaused?: () => boolean;
+}
+/**
+ * Base interface for error handlers.
+ * Standardizes error callback signatures.
+ *
+ * @example
+ * ```typescript
+ * interface ComponentProps extends WithErrorHandler {
+ *   onSuccess?: () => void;
+ * }
+ * ```
+ */
+export interface WithErrorHandler {
+    /** Callback when an error occurs */
+    onError: (error: Error) => void;
+}
+/**
+ * Base interface for success/error callbacks.
+ * Provides standard async operation callbacks.
+ *
+ * @template T - The type of the success data
+ *
+ * @example
+ * ```typescript
+ * interface UploadOptions extends WithCallbacks<File> {
+ *   maxSize: number;
+ * }
+ * ```
+ */
+export interface WithCallbacks<T = void> extends WithErrorHandler {
+    /** Callback when operation succeeds */
+    onSuccess: (data: T) => void;
+}
+/**
+ * Base interface for timeout configuration.
+ * Provides timeout setting.
+ *
+ * @example
+ * ```typescript
+ * interface RequestOptions extends WithTimeout {
+ *   retries?: number;
+ * }
+ * ```
+ */
+export interface WithTimeout {
+    /** Operation timeout in milliseconds */
+    timeout: number;
+}
+/**
+ * Base interface for retry configuration.
+ * Provides retry-related settings.
+ *
+ * @example
+ * ```typescript
+ * interface ApiClientOptions extends WithRetry {
+ *   baseURL: string;
+ * }
+ * ```
+ */
+export interface WithRetry extends WithTimeout {
+    /** Number of retry attempts */
+    retries: number;
+    /** Delay between retries in milliseconds */
+    retryDelay: number;
+}
+/**
+ * Base interface for authored entities.
+ * Tracks who created and last updated an entity.
+ *
+ * @example
+ * ```typescript
+ * interface Document extends Authored {
+ *   content: string;
+ * }
+ * ```
+ */
+export interface Authored {
+    /** User who created this entity */
+    createdBy: string;
+    /** User who last updated this entity */
+    updatedBy: string;
+}
+/**
+ * Base interface for entities with tags.
+ * Provides tagging functionality for categorization.
+ *
+ * @example
+ * ```typescript
+ * interface Article extends WithTags {
+ *   title: string;
+ *   content: string;
+ * }
+ * ```
+ */
+export interface WithTags {
+    /** Tags for categorization */
+    tags: string[];
+}
+/**
+ * Base interface for environment-specific entities.
+ * Specifies which environment(s) an entity applies to.
+ *
+ * @example
+ * ```typescript
+ * interface Config extends WithEnvironment {
+ *   apiUrl: string;
+ * }
+ * ```
+ */
+export interface WithEnvironment {
+    /** Environment(s) this entity applies to */
+    environment: 'development' | 'staging' | 'production' | 'all' | string;
+}
+/**
+ * Base interface for platform-specific entities.
+ * Specifies which platform(s) an entity supports.
+ *
+ * @example
+ * ```typescript
+ * interface AppConfig extends WithPlatform {
+ *   appId: string;
+ * }
+ * ```
+ */
+export interface WithPlatform {
+    /** Platform(s) this entity supports */
+    platform: 'web' | 'ios' | 'android' | 'desktop' | string | string[];
+}
+/**
+ * Base interface for entities with API key.
+ * Provides API key field for authentication.
+ *
+ * @example
+ * ```typescript
+ * interface ServiceConfig extends WithApiKey {
+ *   endpoint: string;
+ * }
+ * ```
+ */
+export interface WithApiKey {
+    /** API key for authentication */
+    apiKey: string;
+}
+/**
+ * Base interface for entities with URL.
+ * Provides URL field for network resources.
+ *
+ * @example
+ * ```typescript
+ * interface WebhookConfig extends WithUrl {
+ *   method: 'POST';
+ * }
+ * ```
+ */
+export interface WithUrl {
+    /** URL of the resource */
+    url: string;
+}
+/**
+ * Base interface for entities with endpoint.
+ * Provides endpoint field for API routes.
+ *
+ * @example
+ * ```typescript
+ * interface ApiRoute extends WithEndpoint {
+ *   method: HttpMethod;
+ * }
+ * ```
+ */
+export interface WithEndpoint {
+    /** API endpoint path */
+    endpoint: string;
+}
+/**
+ * Base interface for entities with base URL.
+ * Provides base URL for API clients.
+ *
+ * @example
+ * ```typescript
+ * interface ApiClient extends WithBaseUrl {
+ *   timeout: number;
+ * }
+ * ```
+ */
+export interface WithBaseUrl {
+    /** Base URL for API requests */
+    baseUrl: string;
+}
+/**
+ * Base interface for key-value pair operations.
+ * Provides generic key-value storage and retrieval.
+ *
+ * @template K - The type of keys
+ * @template V - The type of values
+ * @example
+ * ```typescript
+ * interface Cache extends KeyValueStore<string, unknown> {}
+ * ```
+ */
+export interface KeyValueStore<K = string, V = unknown> {
+    /** Get a value by key */
+    get: (key: K) => V | undefined | Promise<V | undefined>;
+    /** Set a key-value pair */
+    set: (key: K, value: V) => void | Promise<void>;
+    /** Delete a key-value pair */
+    delete: (key: K) => void | Promise<void>;
+    /** Check if a key exists */
+    has: (key: K) => boolean | Promise<boolean>;
+    /** Clear all key-value pairs */
+    clear: () => void | Promise<void>;
+}
+/**
+ * Base interface for a single key-value pair.
+ *
+ * @template K - The type of the key
+ * @template V - The type of the value
+ * @example
+ * ```typescript
+ * interface ConfigEntry extends KeyValuePair<string, string> {}
+ * ```
+ */
+export interface KeyValuePair<K = string, V = unknown> {
+    /** The key */
+    key: K;
+    /** The value */
+    value: V;
+}
+/**
+ * Base interface for entities with key-value pairs.
+ *
+ * @template K - The type of keys
+ * @template V - The type of values
+ * @example
+ * ```typescript
+ * interface Settings extends WithKeyValues<string, boolean> {}
+ * ```
+ */
+export interface WithKeyValues<K = string, V = unknown> {
+    /** Collection of key-value pairs */
+    values: KeyValuePair<K, V>[];
+}
+/**
+ * Base interface for subscription management.
+ * Represents a single subscription with an unsubscribe capability.
+ *
+ * @example
+ * ```typescript
+ * const subscription: Subscription = {
+ *   unsubscribe: () => console.log('Unsubscribed')
+ * };
+ * ```
+ */
+export interface BaseSubscription {
+    /** Function to cancel the subscription */
+    unsubscribe: () => void | Promise<void>;
+}
+/**
+ * Extended subscription with additional metadata.
+ *
+ * @template T - The type of data being subscribed to
+ * @example
+ * ```typescript
+ * const subscription: SubscriptionWithHandler<UserEvent> = {
+ *   id: 'sub-123',
+ *   topic: 'user.created',
+ *   handler: (event) => console.log(event),
+ *   unsubscribe: () => eventBus.off('user.created', handler)
+ * };
+ * ```
+ */
+export interface SubscriptionWithHandler<T = unknown> extends BaseSubscription, Identifiable {
+    /** Topic the handler is subscribed to */
+    topic: string;
+    /** Handler function to invoke when data is published */
+    handler: (data: T) => void | Promise<void>;
+}
+/**
+ * Base interface for entities that support subscribing to events/data.
+ * Provides subscribe capability that returns a Subscription.
+ *
+ * @template T - The type of data being subscribed to
+ * @example
+ * ```typescript
+ * interface Observable<T> extends WithSubscribe<T> {}
+ * ```
+ */
+export interface WithSubscribe<T = unknown> {
+    /** Subscribe to receive data, returns a Subscription for cleanup */
+    subscribe: (callback: (data: T) => void | Promise<void>) => BaseSubscription | Promise<BaseSubscription>;
+}
+/**
+ * Base interface for entities that support publishing events/data.
+ *
+ * @template T - The type of data being published
+ * @example
+ * ```typescript
+ * interface EventEmitter<T> extends WithPublish<T> {}
+ * ```
+ */
+export interface WithPublish<T = unknown> {
+    /** Publish data to subscribers */
+    publish: (data: T) => void | Promise<void>;
+}
+/**
+ * Base interface for subscribable entities with pub/sub pattern.
+ * Combines publish and subscribe capabilities.
+ *
+ * @template T - The type of data being published/subscribed
+ * @example
+ * ```typescript
+ * interface EventBus extends WithSubscribable<Event> {
+ *   // EventBus specific methods
+ * }
+ * ```
+ */
+export interface WithSubscribable<T = unknown> extends WithPublish<T>, WithSubscribe<T> {
+}
+/**
+ * Base interface for topic-based subscription.
+ * Allows subscribing to specific topics/channels.
+ *
+ * @template T - The type of data being subscribed to
+ * @example
+ * ```typescript
+ * interface EventBus extends WithTopicSubscribe<Event> {}
+ * ```
+ */
+export interface WithTopicSubscribe<T = unknown> {
+    /** Subscribe to a specific topic, returns a Subscription for cleanup */
+    subscribe: (topic: string, callback: (data: T) => void | Promise<void>) => BaseSubscription | Promise<BaseSubscription>;
+    /** Unsubscribe from a specific subscription */
+    unsubscribe: (subscriptionId: string) => void | Promise<void>;
+}
+/**
+ * Base interface for topic-based pub/sub pattern.
+ * Combines topic-based publish and subscribe capabilities.
+ *
+ * @template T - The type of data being published/subscribed
+ * @example
+ * ```typescript
+ * interface MessageBus extends WithTopicPubSub<Message> {}
+ * ```
+ */
+export interface WithTopicPubSub<T = unknown> extends WithPublish<T>, WithTopicSubscribe<T> {
+}
+/**
+ * Operation types that can be performed.
+ * Can be combined for specific use cases.
+ */
+export type BaseOperationType = 'create' | 'read' | 'update' | 'delete' | 'evaluate' | 'validate' | 'execute' | 'list' | 'search' | 'filter' | 'sort' | 'paginate' | 'aggregate' | 'transform' | 'subscribe' | 'publish' | 'refresh' | string;
+/**
+ * Base interface for operations with configurable types.
+ * Allows specifying which operations are supported.
+ *
+ * @template T - The allowed operation types
+ * @example
+ * ```typescript
+ * // Read-only operations
+ * interface ReadOnlyOperation extends Operation<'read' | 'list' | 'search'> {
+ *   query: string;
+ * }
+ *
+ * // CRUD operations
+ * interface CrudOperation extends Operation<'create' | 'read' | 'update' | 'delete'> {
+ *   table: string;
+ * }
+ * ```
+ */
+export interface WithOperation<T extends BaseOperationType = BaseOperationType> {
+    /** Type of operation being performed */
+    operation: T;
+}
+/**
+ * Base interface for entities with logging control.
+ * Provides logging configuration.
+ *
+ * @example
+ * ```typescript
+ * interface ServiceOptions extends WithLogging {
+ *   timeout: number;
+ * }
+ * ```
+ */
+export interface WithLogging {
+    /** Whether logging is enabled */
+    isLoggingEnabled: boolean;
+}
+/**
+ * Base interface for refreshable entities.
+ * Provides refresh capability and tracking.
+ *
+ * @example
+ * ```typescript
+ * interface TokenManager extends Refreshable {
+ *   token: string;
+ * }
+ * ```
+ */
+export interface Refreshable {
+    /** When the entity was last updated/refreshed */
+    lastUpdated: Date | string | null;
+    /** Function to refresh the entity */
+    refresh: () => void | Promise<void>;
+}
+/**
+ * Base interface for initializable entities.
+ * Tracks initialization state and readiness.
+ *
+ * @example
+ * ```typescript
+ * interface Service extends Initializable {
+ *   start(): void;
+ * }
+ * ```
+ */
+export interface Initializable {
+    /** Whether the entity has been initialized */
+    isInitialized: boolean;
+    /** Callback when entity is ready */
+    onReady: () => void;
+}
+/**
+ * Base interface for entities with a single timestamp.
+ * Provides basic timestamp tracking.
+ *
+ * @example
+ * ```typescript
+ * interface Event extends WithTimestamp {
+ *   type: string;
+ *   payload: unknown;
+ * }
+ * ```
+ */
+export interface WithTimestamp<T = Date | string> {
+    /** When the event/operation occurred */
+    timestamp: T;
+}
+/**
+ * Base interface for tracked operations.
+ * Provides timestamp and error tracking.
+ *
+ * @typeParam T - Type of the result
+ *
+ * @example
+ * ```typescript
+ * interface ApiCall extends Tracked<Response> {
+ *   endpoint: string;
+ * }
+ * ```
+ */
+export interface Tracked<T = unknown> extends WithTimestamp {
+    /** Result of the operation */
+    result: T | null;
+    /** Error if the operation failed */
+    error: Error | null;
+}
+/**
+ * Base interface for entities with duration tracking.
+ * Provides timing measurement.
+ *
+ * @example
+ * ```typescript
+ * interface PerformanceMetric extends WithDuration {
+ *   name: string;
+ * }
+ * ```
+ */
+export interface WithDuration {
+    /** Duration in milliseconds */
+    duration: number;
+}
+/**
+ * Base interface for entities with last accessed tracking.
+ * Provides access timestamp.
+ *
+ * @example
+ * ```typescript
+ * interface CacheEntry extends WithLastAccessed {
+ *   data: unknown;
+ * }
+ * ```
+ */
+export interface WithLastAccessed {
+    /** When the entity was last accessed */
+    lastAccessedAt: Date | string | null;
+}
+/**
+ * Base interface for versioned entities.
+ * Provides version tracking.
+ *
+ * @example
+ * ```typescript
+ * interface Config extends Versioned {
+ *   settings: unknown;
+ * }
+ * ```
+ */
+export interface Versioned {
+    /** Version identifier */
+    version: string | number;
+}
+/**
+ * Base interface for entities with source tracking.
+ * Identifies where the entity originated.
+ *
+ * @example
+ * ```typescript
+ * interface ImportedData extends WithSource {
+ *   data: unknown;
+ * }
+ * ```
+ */
+export interface WithSource {
+    /** Source identifier */
+    source: string;
+}
+/**
+ * Base interface for entities with status.
+ * Provides status field for state tracking.
+ *
+ * @template T - The type of status values (typically an enum or union type)
+ * @example
+ * ```typescript
+ * interface Task extends WithStatus<'pending' | 'running' | 'completed'> {
+ *   name: string;
+ * }
+ * ```
+ */
+export interface WithStatus<T = string> {
+    /** Current status */
+    status: T;
+}
+/**
+ * Base interface for entities with priority.
+ * Provides priority field for ordering/importance.
+ *
+ * @template T - The type of priority values (typically an enum or union type)
+ * @example
+ * ```typescript
+ * interface Alert extends WithPriority<'low' | 'medium' | 'high' | 'critical'> {
+ *   message: string;
+ * }
+ * ```
+ */
+export interface WithPriority<T = string | number> {
+    /** Priority level */
+    priority: T;
+}
+/**
+ * Base interface for entities with labels.
+ * Provides key-value labeling.
+ *
+ * @example
+ * ```typescript
+ * interface Resource extends WithLabels {
+ *   name: string;
+ * }
+ * ```
+ */
+export interface WithLabels {
+    /** Key-value labels */
+    labels: Record<string, string>;
+}
+/**
+ * Base interface for entities with annotations.
+ * Provides flexible metadata attachment.
+ *
+ * @example
+ * ```typescript
+ * interface Document extends WithAnnotations {
+ *   content: string;
+ * }
+ * ```
+ */
+export interface WithAnnotations {
+    /** Additional annotations */
+    annotations: UnknownRecord;
+}
+/**
+ * Base interface for entities with email.
+ * Provides email field.
+ *
+ * @example
+ * ```typescript
+ * interface UserProfile extends WithEmail {
+ *   name: string;
+ * }
+ * ```
+ */
+export interface WithEmail {
+    /** Email address */
+    email: string;
+}
+/**
+ * Base interface for entities with UUID.
+ * Provides UUID field.
+ *
+ * @example
+ * ```typescript
+ * interface Session extends WithUuid {
+ *   data: unknown;
+ * }
+ * ```
+ */
+export interface WithUuid {
+    /** Universally unique identifier */
+    uuid: string;
+}
+/**
+ * Base interface for entities with user context.
+ * Provides user identification.
+ *
+ * @example
+ * ```typescript
+ * interface Request extends WithUserId {
+ *   action: string;
+ * }
+ * ```
+ */
+export interface WithUserId {
+    /** User identifier */
+    userId: string;
+}
+/**
+ * Base interface for entities with session context.
+ * Provides session identification.
+ *
+ * @example
+ * ```typescript
+ * interface Activity extends WithSessionId {
+ *   action: string;
+ * }
+ * ```
+ */
+export interface WithSessionId {
+    /** Session identifier */
+    sessionId: string;
+}
+/**
+ * Base interface for entities with retry configuration.
+ * Provides retry tracking fields.
+ *
+ * @example
+ * ```typescript
+ * interface RetryableOperation extends WithRetryTracking {
+ *   operation: string;
+ * }
+ * ```
+ */
+export interface WithRetryTracking {
+    /** Current retry attempt count */
+    retryCount: number;
+    /** Maximum allowed retries */
+    maxRetries: number;
+}
+/**
+ * Base interface for entities with roles.
+ * Provides role-based access control.
+ *
+ * @example
+ * ```typescript
+ * interface Account extends WithRoles {
+ *   username: string;
+ * }
+ * ```
+ */
+export interface WithRoles {
+    /** User roles */
+    roles: string[];
+}
+/**
+ * Base interface for entities with permissions.
+ * Provides permission management.
+ *
+ * @example
+ * ```typescript
+ * interface Principal extends WithPermissions {
+ *   id: string;
+ * }
+ * ```
+ */
+export interface WithPermissions {
+    /** User permissions */
+    permissions: string[];
+}
+/**
+ * Base interface for entities with locale.
+ * Provides localization support.
+ *
+ * @example
+ * ```typescript
+ * interface UserSettings extends WithLocale {
+ *   theme: string;
+ * }
+ * ```
+ */
+export interface WithLocale {
+    /** Locale identifier (e.g., 'en-US') */
+    locale: string;
+}
+/**
+ * Base interface for entities with IP address.
+ * Provides IP tracking.
+ *
+ * @example
+ * ```typescript
+ * interface AuditLog extends WithIpAddress {
+ *   action: string;
+ * }
+ * ```
+ */
+export interface WithIpAddress {
+    /** IP address */
+    ip: string;
+}
+/**
+ * Base interface for entities with user agent.
+ * Provides client identification.
+ *
+ * @example
+ * ```typescript
+ * interface Session extends WithUserAgent {
+ *   id: string;
+ * }
+ * ```
+ */
+export interface WithUserAgent {
+    /** User agent string */
+    userAgent: string;
+}
+/**
+ * Base interface for entities with timezone.
+ * Provides timezone information.
+ *
+ * @example
+ * ```typescript
+ * interface UserPreferences extends WithTimezone {
+ *   dateFormat: string;
+ * }
+ * ```
+ */
+export interface WithTimezone {
+    /** Timezone identifier (e.g., 'UTC', 'America/New_York') */
+    timezone: string;
+}
+/**
+ * Base interface for entities with country.
+ * Provides geographical context.
+ *
+ * @example
+ * ```typescript
+ * interface GeoData extends WithCountry {
+ *   city: string;
+ * }
+ * ```
+ */
+export interface WithCountry {
+    /** Country code or name */
+    country: string;
+}
+/**
+ * Base interface for entities with status code.
+ * Provides HTTP/error status.
+ *
+ * @example
+ * ```typescript
+ * interface Response extends WithStatusCode {
+ *   message: string;
+ * }
+ * ```
+ */
+export interface WithStatusCode {
+    /** Status code (HTTP or custom) */
+    statusCode: number;
+}
+/**
+ * Base interface for entities with HTTP status.
+ * Provides HTTP status code and text.
+ *
+ * @example
+ * ```typescript
+ * interface HttpResponse extends WithHttpStatus {
+ *   body: unknown;
+ * }
+ * ```
+ */
+export interface WithHttpStatus {
+    /** HTTP status code */
+    status: number;
+    /** HTTP status text */
+    statusText: string;
+}
+/**
+ * Base interface for entities with request ID.
+ * Provides request tracking.
+ *
+ * @example
+ * ```typescript
+ * interface ApiResponse extends WithRequestId {
+ *   data: unknown;
+ * }
+ * ```
+ */
+export interface WithRequestId {
+    /** Unique request identifier */
+    requestId: string;
+}
+/**
+ * Base interface for entities with correlation ID.
+ * Provides distributed tracing.
+ *
+ * @example
+ * ```typescript
+ * interface Event extends WithCorrelationId {
+ *   type: string;
+ * }
+ * ```
+ */
+export interface WithCorrelationId {
+    /** Correlation ID for tracing */
+    correlationId: string;
+}
+/**
+ * Base interface for entities with path.
+ * Provides path/route information.
+ *
+ * @example
+ * ```typescript
+ * interface RouteError extends WithPath {
+ *   error: Error;
+ * }
+ * ```
+ */
+export interface WithPath {
+    /** Path or route */
+    path: string;
+}
+/**
+ * Base interface for validation results.
+ * Standardizes validation response structure.
+ *
+ * @example
+ * ```typescript
+ * const result: ValidationResult = {
+ *   isValid: false,
+ *   errors: ['Email is required', 'Password too short']
+ * };
+ * ```
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    isValid: boolean;
+    /** Validation error messages */
+    errors: string[];
+}
+/**
+ * Base interface for validation errors with field-level details.
+ * Provides comprehensive validation error information.
+ *
+ * @template Context - Type of additional context information
+ * @example
+ * ```typescript
+ * interface FieldValidationError extends WithValidationError<{ min: number; max: number }> {
+ *   severity: 'error' | 'warning';
+ * }
+ * ```
+ */
+export interface WithValidationError<Context = unknown> extends WithErrorCode, WithMessage {
+    /** The field that caused the validation error */
+    field?: string;
+    /** Additional context about the validation error */
+    context?: Context;
+}
+/**
+ * Base interface for HTTP methods.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * Base interface for entities with HTTP method.
+ *
+ * @example
+ * ```typescript
+ * interface ApiRoute extends WithHttpMethod {
+ *   path: string;
+ * }
+ * ```
+ */
+export interface WithHttpMethod {
+    /** HTTP method for the request */
+    method: HttpMethod;
+}
+/**
+ * Base interface for entities with headers.
+ *
+ * @example
+ * ```typescript
+ * interface Request extends WithHeaders {
+ *   body: unknown;
+ * }
+ * ```
+ */
+export interface WithHeaders {
+    /** HTTP headers */
+    headers: Record<string, string | string[]>;
+}
+/**
+ * Base interface for entities with cookies.
+ * Provides cookie storage.
+ *
+ * @example
+ * ```typescript
+ * interface HttpRequest extends WithCookies {
+ *   url: string;
+ * }
+ * ```
+ */
+export interface WithCookies {
+    /** Cookie key-value pairs */
+    cookies: Record<string, string>;
+}
+/**
+ * Base interface for entities with query parameters.
+ *
+ * @example
+ * ```typescript
+ * interface SearchRequest extends WithQueryParams {
+ *   path: string;
+ * }
+ * ```
+ */
+export interface WithQueryParams {
+    /** Query parameters */
+    query?: Record<string, string | string[] | undefined>;
+}
+/**
+ * Base interface for entities with route parameters.
+ * Provides route/path parameters support.
+ *
+ * @example
+ * ```typescript
+ * interface RouteRequest extends WithParams {
+ *   method: 'GET';
+ * }
+ * ```
+ */
+export interface WithParams {
+    /** Route/path parameters */
+    params: Record<string, Arrayable<string>>;
+}
+/**
+ * Base interface for entities with request body.
+ *
+ * @template T - Type of the body
+ * @example
+ * ```typescript
+ * interface CreateRequest extends WithBody<UserData> {
+ *   method: 'POST';
+ * }
+ * ```
+ */
+export interface WithBody<T = unknown> {
+    /** Request body */
+    body: T;
+}
+/**
+ * Base interface for entities with error information.
+ * Provides standard error fields.
+ *
+ * @example
+ * ```typescript
+ * interface ApiError extends WithError {
+ *   statusCode: number;
+ * }
+ * ```
+ */
+export interface WithError extends WithMessage {
+    /** Error code for programmatic handling */
+    code?: string;
+}
+/**
+ * Base interface for entities with error code.
+ * Provides error code field for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * interface BusinessError extends WithErrorCode {
+ *   details: unknown;
+ * }
+ * ```
+ */
+export interface WithErrorCode {
+    /** Application-specific error code */
+    errorCode: string;
+}
+/**
+ * Base interface for detailed error information.
+ * Provides comprehensive error fields for debugging.
+ *
+ * @example
+ * ```typescript
+ * import type { SetOptional } from 'type-fest';
+ * interface ApiErrorResponse extends WithErrorDetailed {
+ *   requestId: string;
+ * }
+ * // Or with optional path:
+ * interface TestError extends SetOptional<WithErrorDetailed, 'path'> {
+ *   testName: string;
+ * }
+ * ```
+ */
+export interface WithErrorDetailed<T = UnknownRecord> extends WithTimestamp, SetOptional<WithPath, 'path'>, WithMessage, WithStatusCode {
+    /** Error type/name */
+    error: string;
+    /** Additional error details */
+    details?: T;
+}
+/**
+ * Base interface for token-based authentication.
+ * Provides access and refresh token fields.
+ *
+ * @example
+ * ```typescript
+ * interface AuthResponse extends WithTokens {
+ *   user: User;
+ * }
+ * ```
+ */
+export interface WithAuthTokens {
+    /** JWT or opaque access token for API authentication */
+    accessToken: string;
+    /** Token used to obtain new access token when current expires */
+    refreshToken: string;
+}
+/**
+ * Base interface for single token authentication.
+ * Provides a single token field.
+ *
+ * @example
+ * ```typescript
+ * interface ApiKeyAuth extends WithToken {
+ *   expiresAt: Date;
+ * }
+ * ```
+ */
+export interface WithToken {
+    /** Authentication token */
+    token: string;
+}
+/**
+ * Base interface for entities with message.
+ * Provides message field for user-facing information.
+ *
+ * @example
+ * ```typescript
+ * interface Notification extends WithMessage {
+ *   type: 'info' | 'warning' | 'error';
+ * }
+ * ```
+ */
+export interface WithMessage {
+    /** Human-readable message */
+    message: string;
+}
+/**
+ * Base interface for operation results.
+ * Provides success/failure pattern.
+ *
+ * @template T - The type of the result data
+ * @template E - The type of the error data
+ *
+ * @example
+ * ```typescript
+ * const result: Result<User> = {
+ *   success: true,
+ *   data: user,
+ *   error: null,
+ *   message: 'Success'
+ * };
+ * ```
+ */
+export interface Result<T = unknown, E = Error> {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Result data */
+    data: T | null;
+    /** Error if operation failed */
+    error: E | null;
+    /** Status message */
+    message: string;
+}
+/**
+ * Base interface for entities with a slug.
+ * Provides URL-friendly identifier.
+ */
+export interface Sluggable {
+    /** URL-friendly identifier */
+    slug: string;
+}
+/**
+ * Base interface for entities with categories.
+ * Provides categorization support.
+ */
+export interface WithCategories {
+    /** Array of category names or identifiers */
+    categories: string[];
+}
+/**
+ * Base interface for HTTP response status.
+ * Provides status code and message.
+ */
+export interface WithStatusMessage {
+    /** HTTP status message */
+    statusMessage: string;
+}