@oxog/types 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,945 @@
+/**
+ * @oxog/types - Common TypeScript utility types
+ * @version 1.0.0
+ * @author Ersin Koç
+ */
+/** Brand symbol for branded types */
+declare const __brand: unique symbol;
+/**
+ * Creates a branded type for type-safe identifiers.
+ *
+ * Branded types allow you to create distinct types that share the same
+ * underlying representation, preventing accidental type mixing.
+ *
+ * @example
+ * ```typescript
+ * type UserId = Branded<string, 'UserId'>;
+ * type OrderId = Branded<string, 'OrderId'>;
+ *
+ * const userId: UserId = 'user_123' as UserId;
+ * const orderId: OrderId = 'order_456' as OrderId;
+ *
+ * // Type error: Type 'UserId' is not assignable to type 'OrderId'
+ * const wrong: OrderId = userId;
+ * ```
+ */
+type Branded<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+/**
+ * Shorthand for Branded.
+ *
+ * @example
+ * ```typescript
+ * type ProductId = Brand<number, 'ProductId'>;
+ * ```
+ */
+type Brand<T, B extends string> = Branded<T, B>;
+/**
+ * Deep partial - all nested properties optional.
+ *
+ * Recursively makes all properties and nested properties optional.
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   name: string;
+ *   address: {
+ *     street: string;
+ *     city: string;
+ *   };
+ * }
+ *
+ * const partial: DeepPartial<User> = {
+ *   name: 'John',
+ *   address: {
+ *     street: 'Main St'
+ *     // city is optional
+ *   }
+ * };
+ * ```
+ */
+type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+/**
+ * Deep readonly - all nested properties readonly.
+ *
+ * Recursively makes all properties and nested properties readonly.
+ *
+ * @example
+ * ```typescript
+ * interface Config {
+ *   api: {
+ *     url: string;
+ *     timeout: number;
+ *   };
+ * }
+ *
+ * const readonlyConfig: DeepReadonly<Config> = {
+ *   api: {
+ *     url: 'https://api.example.com',
+ *     timeout: 5000
+ *   }
+ * };
+ *
+ * // Type error: Cannot assign to 'url' because it is a read-only property
+ * readonlyConfig.api.url = 'https://other.com';
+ * ```
+ */
+type DeepReadonly<T> = T extends object ? {
+    readonly [P in keyof T]: DeepReadonly<T[P]>;
+} : T;
+/**
+ * Deep required - all nested properties required.
+ *
+ * Recursively removes optional markers from all properties and nested properties.
+ *
+ * @example
+ * ```typescript
+ * interface OptionalUser {
+ *   name?: string;
+ *   address?: {
+ *     street?: string;
+ *     city?: string;
+ *   };
+ * }
+ *
+ * const required: DeepRequired<OptionalUser> = {
+ *   name: 'John',
+ *   address: {
+ *     street: 'Main St',
+ *     city: 'NYC'
+ *   }
+ * };
+ * ```
+ */
+type DeepRequired<T> = T extends object ? {
+    [P in keyof T]-?: DeepRequired<T[P]>;
+} : T;
+/**
+ * Value that may be a promise.
+ *
+ * Represents a value that can be either synchronous or asynchronous.
+ *
+ * @example
+ * ```typescript
+ * function process(data: string): MaybePromise<string> {
+ *   if (useCache) {
+ *     return cachedData; // Synchronous
+ *   }
+ *   return fetchData(); // Promise
+ * }
+ * ```
+ */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Any function type.
+ *
+ * Represents any callable function with any arguments and return type.
+ */
+type AnyFunction = (...args: any[]) => any;
+/**
+ * Async function type.
+ *
+ * Represents an asynchronous function.
+ *
+ * @example
+ * ```typescript
+ * const fetchData: AsyncFunction<string> = async () => {
+ *   return await fetch('/api/data').then(r => r.text());
+ * };
+ * ```
+ */
+type AsyncFunction<T = unknown> = (...args: any[]) => Promise<T>;
+/**
+ * Sync function type.
+ *
+ * Represents a synchronous function.
+ *
+ * @example
+ * ```typescript
+ * const add: SyncFunction<number> = (a: number, b: number) => {
+ *   return a + b;
+ * };
+ * ```
+ */
+type SyncFunction<T = unknown> = (...args: any[]) => T;
+/**
+ * JSON primitive types.
+ *
+ * Represents valid JSON primitive values.
+ */
+type JsonPrimitive = string | number | boolean | null;
+/**
+ * JSON array type.
+ *
+ * Represents a JSON array of JsonValue elements.
+ */
+type JsonArray = JsonValue[];
+/**
+ * JSON object type.
+ *
+ * Represents a JSON object with string keys and JsonValue values.
+ */
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * Any valid JSON value.
+ *
+ * Represents any value that can be serialized to JSON.
+ */
+type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+/**
+ * Make type prettier in IDE.
+ *
+ * Utility type that flattens type structure for better IDE display.
+ *
+ * @example
+ * ```typescript
+ * type ComplexType = { a: string } & { b: number };
+ * type PrettyType = Prettify<ComplexType>;
+ * // IDE shows properties directly instead of intersection
+ * ```
+ */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Strict omit that requires valid keys.
+ *
+ * Like TypeScript's Omit, but ensures the keys exist in the type.
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * // Only 'id' and 'name' allowed - TypeScript will error on invalid keys
+ * type UserWithoutEmail = StrictOmit<User, 'email'>;
+ * ```
+ */
+type StrictOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+/**
+ * Strict pick that requires valid keys.
+ *
+ * Like TypeScript's Pick, but ensures the keys exist in the type.
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * // Only 'id' and 'name' allowed - TypeScript will error on invalid keys
+ * type UserBasicInfo = StrictPick<User, 'id' | 'name'>;
+ * ```
+ */
+type StrictPick<T, K extends keyof T> = Pick<T, K>;
+/**
+ * Array with at least one element.
+ *
+ * Represents arrays that are guaranteed to have at least one element.
+ *
+ * @example
+ * ```typescript
+ * const nonEmpty: NonEmptyArray<number> = [1];
+ * const nonEmpty2: NonEmptyArray<string> = ['hello', 'world'];
+ *
+ * // Type error: Argument of type 'number[]' is not assignable
+ * const empty: NonEmptyArray<number> = [];
+ * ```
+ */
+type NonEmptyArray<T> = [T, ...T[]];
+/**
+ * Value that can be null.
+ *
+ * Alias for nullable types.
+ *
+ * @example
+ * ```typescript
+ * const value: Nullable<string> = null;
+ * const value2: Nullable<number> = 42;
+ * ```
+ */
+type Nullable<T> = T | null;
+/**
+ * Value that can be undefined.
+ *
+ * Alias for optional types.
+ *
+ * @example
+ * ```typescript
+ * const value: Optional<string> = undefined;
+ * const value2: Optional<number> = 123;
+ * ```
+ */
+type Optional<T> = T | undefined;
+/**
+ * Unsubscribe function returned by event subscriptions.
+ *
+ * Call this function to unsubscribe from an event.
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = eventEmitter.on('event', handler);
+ * // Later, when done listening:
+ * unsubscribe();
+ * ```
+ */
+type Unsubscribe = () => void;
+
+/**
+ * @oxog/types - Plugin and Kernel interfaces
+ * @version 1.0.0
+ * @author Ersin Koç
+ */
+
+/**
+ * Standard plugin interface for @oxog ecosystem.
+ *
+ * A plugin is a self-contained module that can be registered with a Kernel.
+ * Plugins can depend on other plugins and communicate through the Kernel's
+ * event system.
+ *
+ * @example
+ * ```typescript
+ * const myPlugin: Plugin = {
+ *   name: 'my-plugin',
+ *   version: '1.0.0',
+ *   dependencies: ['logger'],
+ *   install(kernel) {
+ *     kernel.on('init', () => console.log('Plugin installed'));
+ *   },
+ *   onInit(context) {
+ *     // Called after all plugins installed
+ *   },
+ *   onDestroy() {
+ *     // Cleanup resources
+ *   },
+ *   onError(error) {
+ *     console.error('Plugin error:', error);
+ *   }
+ * };
+ * ```
+ */
+interface Plugin<TContext = unknown> {
+    /** Unique plugin identifier (kebab-case) */
+    readonly name: string;
+    /** Semantic version (e.g., "1.0.0") */
+    readonly version: string;
+    /** Plugin dependencies by name */
+    readonly dependencies?: readonly string[];
+    /** Called when plugin is registered with the kernel */
+    install: (kernel: Kernel<TContext>) => void;
+    /** Called after ALL plugins are installed */
+    onInit?: (context: TContext) => MaybePromise<void>;
+    /** Called when plugin is unregistered */
+    onDestroy?: () => MaybePromise<void>;
+    /** Called when an error occurs in this plugin */
+    onError?: (error: Error) => void;
+}
+/**
+ * Micro-kernel interface for @oxog packages.
+ *
+ * The Kernel manages plugins and provides event communication between them.
+ * It maintains a plugin registry and exposes methods for plugin lifecycle
+ * management.
+ *
+ * @example
+ * ```typescript
+ * // Register a plugin
+ * kernel.use(myPlugin);
+ *
+ * // Get a plugin
+ * const plugin = kernel.getPlugin('logger');
+ *
+ * // Check if plugin exists
+ * if (kernel.hasPlugin('logger')) {
+ *   // Plugin is registered
+ * }
+ *
+ * // Emit event
+ * kernel.emit('user:login', { userId: '123' });
+ *
+ * // Subscribe to events
+ * const unsubscribe = kernel.on('user:login', (payload) => {
+ *   console.log('User logged in:', payload);
+ * });
+ * ```
+ */
+interface Kernel<TContext = unknown> {
+    /** Register a plugin */
+    use(plugin: Plugin<TContext>): this;
+    /** Unregister a plugin by name */
+    unregister(name: string): boolean;
+    /** Get registered plugin by name */
+    getPlugin<T extends Plugin<TContext> = Plugin<TContext>>(name: string): T | undefined;
+    /** List all registered plugins */
+    listPlugins(): ReadonlyArray<Plugin<TContext>>;
+    /** Check if plugin is registered */
+    hasPlugin(name: string): boolean;
+    /** Emit event to all plugins */
+    emit<K extends string>(event: K, payload?: unknown): void;
+    /** Subscribe to kernel events */
+    on<K extends string>(event: K, handler: (payload: unknown) => void): Unsubscribe;
+    /** Get shared context */
+    getContext(): TContext;
+}
+/**
+ * Plugin options for configuration.
+ *
+ * Configuration options that can be passed when creating or configuring
+ * a plugin-enabled application.
+ *
+ * @example
+ * ```typescript
+ * const options: PluginOptions = {
+ *   debug: true,
+ *   logger: console
+ * };
+ * ```
+ */
+interface PluginOptions {
+    /** Whether to enable debug mode */
+    debug?: boolean;
+    /** Custom logger */
+    logger?: PluginLogger;
+}
+/**
+ * Plugin logger interface.
+ *
+ * Standard logging interface that plugins can use to log messages.
+ * This abstraction allows custom logging implementations.
+ *
+ * @example
+ * ```typescript
+ * const logger: PluginLogger = {
+ *   debug(message, ...args) { console.log('[DEBUG]', message, ...args); },
+ *   info(message, ...args) { console.log('[INFO]', message, ...args); },
+ *   warn(message, ...args) { console.warn('[WARN]', message, ...args); },
+ *   error(message, ...args) { console.error('[ERROR]', message, ...args); }
+ * };
+ * ```
+ */
+interface PluginLogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * Result type - either Ok<T> or Err<E>.
+ *
+ * A type that represents either success (Ok) or failure (Err).
+ * This is inspired by Rust's Result type and provides functional
+ * error handling without exceptions.
+ *
+ * @example
+ * ```typescript
+ * function divide(a: number, b: number): Result<number, string> {
+ *   if (b === 0) {
+ *     return Err('Division by zero');
+ *   }
+ *   return Ok(a / b);
+ * }
+ *
+ * const result = divide(10, 2);
+ *
+ * // Pattern matching
+ * const message = result.match({
+ *   ok: (value) => `Result: ${value}`,
+ *   err: (error) => `Error: ${error}`
+ * });
+ *
+ * // Chaining
+ * const doubled = result
+ *   .map(x => x * 2)
+ *   .mapErr(e => `Calculation failed: ${e}`);
+ * ```
+ */
+type Result<T, E> = Ok<T> | Err<E>;
+/**
+ * @oxog/types - Result type for functional error handling
+ * @version 1.0.0
+ * @author Ersin Koç
+ */
+/**
+ * Represents a successful result.
+ *
+ * Contains a value and provides methods for transforming the value
+ * or handling errors. Only available on successful results.
+ *
+ * @example
+ * ```typescript
+ * const ok = Ok(42);
+ * if (isOk(ok)) {
+ *   console.log(ok.value); // 42
+ * }
+ * ```
+ */
+interface Ok<T> {
+    readonly ok: true;
+    readonly value: T;
+    readonly error?: never;
+    /** Transform the value if successful */
+    map<U>(fn: (value: T) => U): Result<U, never>;
+    /** Transform the error (no-op for Ok) */
+    mapErr<F>(fn: (error: never) => F): Ok<T>;
+    /** Pattern matching for both cases */
+    match<U>(handlers: {
+        ok: (value: T) => U;
+        err: (error: never) => U;
+    }): U;
+    /** Unwrap the value (asserts success) */
+    unwrap(): T;
+    /** Unwrap with default value */
+    unwrapOr(defaultValue: T): T;
+    /** Unwrap using a fallback function */
+    unwrapOrElse(fn: () => T): T;
+}
+/**
+ * Creates a successful Result containing a value.
+ *
+ * @example
+ * ```typescript
+ * const ok = Ok(42);
+ * const okStr = Ok('hello');
+ * const okObj = Ok({ id: 1 });
+ * ```
+ *
+ * @param value - The value to wrap
+ * @returns An Ok result containing the value
+ */
+declare function Ok<T>(value: T): Ok<T>;
+/**
+ * Represents a failed result.
+ *
+ * Contains an error and provides methods for transforming the error
+ * or handling success cases. Only available on failed results.
+ *
+ * @example
+ * ```typescript
+ * const err = Err('Something went wrong');
+ * if (isErr(err)) {
+ *   console.log(err.error); // 'Something went wrong'
+ * }
+ * ```
+ */
+interface Err<E> {
+    readonly ok: false;
+    readonly value?: never;
+    readonly error: E;
+    /** Transform the value (no-op for Err) */
+    map<U>(fn: (value: never) => U): Err<E>;
+    /** Transform the error if failed */
+    mapErr<F>(fn: (error: E) => F): Result<never, F>;
+    /** Pattern matching for both cases */
+    match<U>(handlers: {
+        ok: (value: never) => U;
+        err: (error: E) => U;
+    }): U;
+    /** Unwrap the value (asserts success, throws for Err) */
+    unwrap(): never;
+    /** Unwrap with default value */
+    unwrapOr<T>(defaultValue: T): T;
+    /** Unwrap using a fallback function */
+    unwrapOrElse<T>(fn: () => T): T;
+}
+/**
+ * Creates a failed Result containing an error.
+ *
+ * @example
+ * ```typescript
+ * const err = Err('Something went wrong');
+ * const errNum = Err(404);
+ * const errObj = Err({ code: 'NOT_FOUND' });
+ * ```
+ *
+ * @param error - The error to wrap
+ * @returns An Err result containing the error
+ */
+declare function Err<E>(error: E): Err<E>;
+
+/**
+ * @oxog/types - Standardized error classes
+ * @version 1.0.0
+ * @author Ersin Koç
+ */
+/**
+ * Standard error codes for @oxog ecosystem.
+ *
+ * These codes provide programmatic ways to identify and handle errors.
+ */
+declare enum ErrorCodes {
+    /** Unknown error */
+    UNKNOWN = "UNKNOWN",
+    /** Validation error */
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** Plugin-related error */
+    PLUGIN_ERROR = "PLUGIN_ERROR",
+    /** Resource not found */
+    NOT_FOUND = "NOT_FOUND",
+    /** Operation timed out */
+    TIMEOUT = "TIMEOUT",
+    /** Dependency error */
+    DEPENDENCY_ERROR = "DEPENDENCY_ERROR"
+}
+/**
+ * Base error class for all @oxog errors.
+ *
+ * Provides structured error information with code, message, and context.
+ * All other @oxog errors inherit from this class.
+ *
+ * @example
+ * ```typescript
+ * throw new OxogError(
+ *   'Database connection failed',
+ *   ErrorCodes.DEPENDENCY_ERROR,
+ *   { host: 'localhost', port: 5432 }
+ * );
+ * ```
+ */
+declare class OxogError extends Error {
+    readonly code: string;
+    readonly context?: Record<string, unknown> | undefined;
+    /** Error name */
+    readonly name: string;
+    /**
+     * Creates a new OxogError.
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param context - Additional context about the error
+     */
+    constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Error thrown when validation fails.
+ *
+ * Used for input validation, schema validation, and type checking errors.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError(
+ *   'Invalid email format',
+ *   { field: 'email', value: 'not-an-email' }
+ * );
+ * ```
+ */
+declare class ValidationError extends OxogError {
+    readonly context?: Record<string, unknown> | undefined;
+    /** Error name */
+    readonly name: string;
+    /**
+     * Creates a new ValidationError.
+     *
+     * @param message - Human-readable error message
+     * @param context - Additional context about the validation failure
+     */
+    constructor(message: string, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Error thrown when a plugin operation fails.
+ *
+ * Used for plugin initialization, dependency resolution, and runtime errors
+ * specific to plugins.
+ *
+ * @example
+ * ```typescript
+ * throw new PluginError(
+ *   'Failed to initialize cache plugin',
+ *   'cache-plugin',
+ *   { reason: 'Redis connection failed' }
+ * );
+ * ```
+ */
+declare class PluginError extends OxogError {
+    readonly pluginName: string;
+    /** Error name */
+    readonly name: string;
+    /**
+     * Creates a new PluginError.
+     *
+     * @param message - Human-readable error message
+     * @param pluginName - Name of the plugin that caused the error
+     * @param context - Additional context about the plugin error
+     */
+    constructor(message: string, pluginName: string, context?: Record<string, unknown>);
+}
+
+/**
+ * @oxog/types - Type guard functions
+ * @version 1.0.0
+ * @author Ersin Koç
+ */
+
+/**
+ * Type guard for Plugin.
+ *
+ * Checks if a value is a valid Plugin instance.
+ *
+ * @example
+ * ```typescript
+ * const plugin = { name: 'test', version: '1.0.0', install: () => {} };
+ * if (isPlugin(plugin)) {
+ *   console.log(plugin.name); // TypeScript knows it's a Plugin
+ * }
+ * ```
+ */
+declare function isPlugin<T>(value: unknown): value is Plugin<T>;
+/**
+ * Type guard for Kernel.
+ *
+ * Checks if a value is a valid Kernel instance.
+ *
+ * @example
+ * ```typescript
+ * const kernel = {
+ *   use: (plugin) => kernel,
+ *   unregister: () => true,
+ *   getPlugin: () => undefined,
+ *   listPlugins: () => [],
+ *   hasPlugin: () => false,
+ *   emit: () => {},
+ *   on: () => () => {},
+ *   getContext: () => null
+ * };
+ * if (isKernel(kernel)) {
+ *   console.log(kernel.listPlugins()); // TypeScript knows it's a Kernel
+ * }
+ * ```
+ */
+declare function isKernel<T>(value: unknown): value is Kernel<T>;
+/**
+ * Type guard for OxogError.
+ *
+ * Checks if a value is an OxogError instance.
+ *
+ * @example
+ * ```typescript
+ * const error = new OxogError('Test', 'TEST');
+ * if (isOxogError(error)) {
+ *   console.log(error.code); // TypeScript knows it's an OxogError
+ * }
+ * ```
+ */
+declare function isOxogError(value: unknown): value is OxogError;
+/**
+ * Type guard for ValidationError.
+ *
+ * Checks if a value is a ValidationError instance.
+ *
+ * @example
+ * ```typescript
+ * const error = new ValidationError('Invalid', { field: 'test' });
+ * if (isValidationError(error)) {
+ *   console.log(error.context); // TypeScript knows it's a ValidationError
+ * }
+ * ```
+ */
+declare function isValidationError(value: unknown): value is ValidationError;
+/**
+ * Type guard for PluginError.
+ *
+ * Checks if a value is a PluginError instance.
+ *
+ * @example
+ * ```typescript
+ * const error = new PluginError('Plugin failed', 'my-plugin');
+ * if (isPluginError(error)) {
+ *   console.log(error.pluginName); // TypeScript knows it's a PluginError
+ * }
+ * ```
+ */
+declare function isPluginError(value: unknown): value is PluginError;
+/**
+ * Type guard for Result.
+ *
+ * Checks if a value is a Result instance (either Ok or Err).
+ *
+ * @example
+ * ```typescript
+ * const result = Ok(42);
+ * if (isResult(result)) {
+ *   // result is Ok<number, unknown>
+ * }
+ *
+ * const err = Err('error');
+ * if (isResult(err)) {
+ *   // err is Err<unknown, string>
+ * }
+ * ```
+ */
+declare function isResult<T, E>(value: unknown): value is Result<T, E>;
+/**
+ * Type guard for Ok result.
+ *
+ * Checks if a Result is an Ok (success) instance.
+ *
+ * @example
+ * ```typescript
+ * const ok = Ok(42);
+ * if (isOk(ok)) {
+ *   console.log(ok.value); // TypeScript knows it's Ok
+ * }
+ * ```
+ */
+declare function isOk<T>(value: Result<T, unknown>): value is Ok<T>;
+/**
+ * Type guard for Err result.
+ *
+ * Checks if a Result is an Err (failure) instance.
+ *
+ * @example
+ * ```typescript
+ * const err = Err('error');
+ * if (isErr(err)) {
+ *   console.log(err.error); // TypeScript knows it's Err
+ * }
+ * ```
+ */
+declare function isErr<E>(value: Result<unknown, E>): value is Err<E>;
+
+/**
+ * @oxog/types - Event system types
+ * @version 1.0.0
+ * @author Ersin Koç
+ */
+
+/**
+ * Base event map interface.
+ *
+ * Defines the structure for event payloads. Extend this interface
+ * to define custom events for your application.
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents extends EventMap {
+ *   'user:login': { userId: string; timestamp: number };
+ *   'user:logout': { userId: string };
+ *   'error': Error;
+ * }
+ * ```
+ */
+interface EventMap {
+    [event: string]: unknown;
+}
+/**
+ * Event handler for a specific event.
+ *
+ * Type-safe event handler that receives the correctly typed payload.
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents extends EventMap {
+ *   'user:login': { userId: string; timestamp: number };
+ * }
+ *
+ * const handler: EventHandler<MyEvents, 'user:login'> = (payload) => {
+ *   console.log(payload.userId, payload.timestamp);
+ * };
+ * ```
+ */
+type EventHandler<TEvents extends EventMap, K extends keyof TEvents> = (payload: TEvents[K]) => void;
+/**
+ * Typed event emitter interface.
+ *
+ * Provides type-safe event emission and subscription. Implement this
+ * interface to create custom event emitters.
+ *
+ * @example
+ * ```typescript
+ * class MyEmitter implements TypedEventEmitter<MyEvents> {
+ *   private handlers = new Map<string, Set<Function>>();
+ *
+ *   on<K extends keyof MyEvents>(event: K, handler: EventHandler<MyEvents, K>): Unsubscribe {
+ *     // Implementation
+ *     return () => {};
+ *   }
+ *
+ *   off<K extends keyof MyEvents>(event: K, handler: EventHandler<MyEvents, K>): void {
+ *     // Implementation
+ *   }
+ *
+ *   emit<K extends keyof MyEvents>(event: K, payload: MyEvents[K]): void {
+ *     // Implementation
+ *   }
+ *
+ *   once<K extends keyof MyEvents>(event: K, handler: EventHandler<MyEvents, K>): Unsubscribe {
+ *     // Implementation
+ *     return () => {};
+ *   }
+ * }
+ * ```
+ */
+interface TypedEventEmitter<TEvents extends EventMap> {
+    /** Subscribe to an event */
+    on<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents, K>): Unsubscribe;
+    /** Unsubscribe from an event */
+    off<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents, K>): void;
+    /** Emit an event */
+    emit<K extends keyof TEvents>(event: K, payload: TEvents[K]): void;
+    /** Subscribe to an event exactly once */
+    once<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents, K>): Unsubscribe;
+}
+
+/**
+ * @oxog/types - Well-known symbols and constants
+ * @version 1.0.0
+ * @author Ersin Koç
+ */
+
+/**
+ * Well-known symbol for @oxog plugins.
+ *
+ * Use this symbol to mark objects as @oxog plugins.
+ * This enables runtime detection and validation.
+ *
+ * @example
+ * ```typescript
+ * const myPlugin = {
+ *   [OXOG_PLUGIN]: true,
+ *   name: 'my-plugin',
+ *   version: '1.0.0',
+ *   install: () => {}
+ * };
+ * ```
+ */
+declare const OXOG_PLUGIN: unique symbol;
+/**
+ * Well-known symbol for @oxog kernels.
+ *
+ * Use this symbol to mark objects as @oxog kernels.
+ * This enables runtime detection and validation.
+ *
+ * @example
+ * ```typescript
+ * const myKernel = {
+ *   [OXOG_KERNEL]: true,
+ *   use: (plugin) => kernel,
+ *   // ... other methods
+ * };
+ * ```
+ */
+declare const OXOG_KERNEL: unique symbol;
+/**
+ * @oxog/types package version.
+ *
+ * Current version of the @oxog/types package.
+ *
+ * @example
+ * ```typescript
+ * console.log(`Using @oxog/types v${OXOG_VERSION}`);
+ * ```
+ */
+declare const OXOG_VERSION = "1.0.0";
+
+export { type AnyFunction, type AsyncFunction, type Brand, type Branded, type DeepPartial, type DeepReadonly, type DeepRequired, Err, ErrorCodes, type EventHandler, type EventMap, type JsonArray, type JsonObject, type JsonPrimitive, type JsonValue, type Kernel, type MaybePromise, type NonEmptyArray, type Nullable, OXOG_KERNEL, OXOG_PLUGIN, OXOG_VERSION, Ok, type Optional, OxogError, type Plugin, PluginError, type PluginLogger, type PluginOptions, type Prettify, type Result, type StrictOmit, type StrictPick, type SyncFunction, type TypedEventEmitter, type Unsubscribe, ValidationError, isErr, isKernel, isOk, isOxogError, isPlugin, isPluginError, isResult, isValidationError };