@mohasinac/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,202 @@
+/**
+ * Logger Class — @mohasinac/core
+ *
+ * Singleton class for application logging.
+ * Pure utility — no framework or app-specific imports.
+ *
+ * The `logFileUrl` constructor option replaces the previous app-specific
+ * `import("@/constants")` call, making this usable in any context.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: Date;
+    data?: unknown;
+}
+interface LoggerOptions {
+    minLevel?: LogLevel;
+    enableConsole?: boolean;
+    enableStorage?: boolean;
+    /**
+     * URL to POST error log entries. Set to your `/api/logs/write` route.
+     */
+    logFileUrl?: string;
+    /**
+     * @deprecated Prefer `logFileUrl`. When `true` and `logFileUrl` is not set,
+     * defaults to `/api/logs/write` for backward compatibility with the
+     * previous app-coupled Logger implementation.
+     */
+    enableFileLogging?: boolean;
+    maxEntries?: number;
+    /** Optional function to sanitize data before logging (e.g., PII redaction). */
+    sanitizer?: (data: unknown) => unknown;
+}
+declare class Logger {
+    private static instance;
+    private logs;
+    private options;
+    private levelPriority;
+    private constructor();
+    /** Get singleton instance */
+    static getInstance(options?: LoggerOptions): Logger;
+    /** Set or update the data sanitizer (e.g., for PII redaction). */
+    static setSanitizer(fn: (data: unknown) => unknown): void;
+    private shouldLog;
+    private addLog;
+    private logToConsole;
+    private saveToStorage;
+    private writeToFile;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    getLogs(level?: LogLevel): LogEntry[];
+    clear(): void;
+    export(): string;
+    getStats(): Record<LogLevel, number>;
+}
+/** Shared singleton instance */
+declare const logger: Logger;
+
+/**
+ * Queue Class — @mohasinac/core
+ *
+ * Generic priority queue for task management.
+ * Pure utility — no framework or app-specific imports.
+ */
+interface QueueOptions {
+    concurrency?: number;
+    autoStart?: boolean;
+}
+interface Task<T = unknown> {
+    id: string;
+    fn: () => Promise<T>;
+    priority?: number;
+}
+declare class Queue<T = unknown> {
+    private tasks;
+    private running;
+    private readonly concurrency;
+    private autoStart;
+    private results;
+    private errors;
+    constructor(options?: QueueOptions);
+    /** Add a task to the queue */
+    add(id: string, fn: () => Promise<T>, priority?: number): void;
+    private process;
+    start(): void;
+    pause(): void;
+    resume(): void;
+    clear(): void;
+    getResult(id: string): T | undefined;
+    getError(id: string): Error | undefined;
+    size(): number;
+    getRunning(): number;
+    isEmpty(): boolean;
+    waitForCompletion(): Promise<void>;
+    getStats(): {
+        pending: number;
+        running: number;
+        completed: number;
+        failed: number;
+    };
+}
+
+/**
+ * StorageManager Class — @mohasinac/core
+ *
+ * Singleton class for managing localStorage and sessionStorage with
+ * namespace prefixing and SSR-safe fallbacks.
+ * Pure utility — no framework or app-specific imports.
+ */
+type StorageType = "local" | "session";
+interface StorageOptions {
+    type?: StorageType;
+    prefix?: string;
+}
+declare class StorageManager {
+    /** Per-prefix instance map — prevents namespace collisions */
+    private static instances;
+    private readonly prefix;
+    private constructor();
+    /**
+     * Get-or-create a StorageManager for the given prefix.
+     * Each prefix returns an independent instance.
+     */
+    static getInstance(prefix?: string): StorageManager;
+    private getStorage;
+    private generateKey;
+    set<T>(key: string, value: T, options?: StorageOptions): boolean;
+    get<T>(key: string, options?: StorageOptions): T | null;
+    remove(key: string, options?: StorageOptions): boolean;
+    clear(options?: StorageOptions): boolean;
+    has(key: string, options?: StorageOptions): boolean;
+    keys(options?: StorageOptions): string[];
+    size(options?: StorageOptions): number;
+    isAvailable(type?: StorageType): boolean;
+    getAll<T = unknown>(options?: StorageOptions): Record<string, T>;
+}
+/** Default StorageManager instance (empty prefix) */
+declare const storageManager: StorageManager;
+
+/**
+ * EventBus Class — @mohasinac/core
+ *
+ * Singleton pub/sub event bus for decoupled communication.
+ * Pure utility — no framework or app-specific imports.
+ */
+type EventCallback = (...args: any[]) => void;
+interface EventSubscription {
+    unsubscribe: () => void;
+}
+declare class EventBus {
+    private static instance;
+    private readonly events;
+    private constructor();
+    static getInstance(): EventBus;
+    on(event: string, callback: EventCallback): EventSubscription;
+    once(event: string, callback: EventCallback): EventSubscription;
+    off(event: string, callback: EventCallback): void;
+    emit(event: string, ...args: any[]): void;
+    removeAllListeners(event?: string): void;
+    listenerCount(event: string): number;
+    eventNames(): string[];
+    hasListeners(event: string): boolean;
+}
+/** Shared singleton instance */
+declare const eventBus: EventBus;
+
+/**
+ * CacheManager Class — @mohasinac/core
+ *
+ * Simple TTL-based in-memory cache with FIFO eviction.
+ * Pure utility — no framework or app-specific imports.
+ */
+interface CacheOptions {
+    ttl?: number;
+}
+interface CacheEntry<T> {
+    value: T;
+    timestamp: number;
+    ttl?: number;
+}
+declare class CacheManager {
+    private static instance;
+    private readonly cache;
+    private readonly maxSize;
+    private constructor();
+    static getInstance(maxSize?: number): CacheManager;
+    set<T>(key: string, value: T, options?: CacheOptions): void;
+    get<T>(key: string): T | null;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    size(): number;
+    keys(): string[];
+    cleanExpired(): number;
+}
+/** Default shared CacheManager singleton */
+declare const cacheManager: CacheManager;
+
+export { type CacheEntry, CacheManager, type CacheOptions, EventBus, type EventSubscription, type LogEntry, type LogLevel, Logger, type LoggerOptions, Queue, type QueueOptions, StorageManager, type StorageOptions, type StorageType, type Task, cacheManager, eventBus, logger, storageManager };

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Logger Class — @mohasinac/core
+ *
+ * Singleton class for application logging.
+ * Pure utility — no framework or app-specific imports.
+ *
+ * The `logFileUrl` constructor option replaces the previous app-specific
+ * `import("@/constants")` call, making this usable in any context.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: Date;
+    data?: unknown;
+}
+interface LoggerOptions {
+    minLevel?: LogLevel;
+    enableConsole?: boolean;
+    enableStorage?: boolean;
+    /**
+     * URL to POST error log entries. Set to your `/api/logs/write` route.
+     */
+    logFileUrl?: string;
+    /**
+     * @deprecated Prefer `logFileUrl`. When `true` and `logFileUrl` is not set,
+     * defaults to `/api/logs/write` for backward compatibility with the
+     * previous app-coupled Logger implementation.
+     */
+    enableFileLogging?: boolean;
+    maxEntries?: number;
+    /** Optional function to sanitize data before logging (e.g., PII redaction). */
+    sanitizer?: (data: unknown) => unknown;
+}
+declare class Logger {
+    private static instance;
+    private logs;
+    private options;
+    private levelPriority;
+    private constructor();
+    /** Get singleton instance */
+    static getInstance(options?: LoggerOptions): Logger;
+    /** Set or update the data sanitizer (e.g., for PII redaction). */
+    static setSanitizer(fn: (data: unknown) => unknown): void;
+    private shouldLog;
+    private addLog;
+    private logToConsole;
+    private saveToStorage;
+    private writeToFile;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    getLogs(level?: LogLevel): LogEntry[];
+    clear(): void;
+    export(): string;
+    getStats(): Record<LogLevel, number>;
+}
+/** Shared singleton instance */
+declare const logger: Logger;
+
+/**
+ * Queue Class — @mohasinac/core
+ *
+ * Generic priority queue for task management.
+ * Pure utility — no framework or app-specific imports.
+ */
+interface QueueOptions {
+    concurrency?: number;
+    autoStart?: boolean;
+}
+interface Task<T = unknown> {
+    id: string;
+    fn: () => Promise<T>;
+    priority?: number;
+}
+declare class Queue<T = unknown> {
+    private tasks;
+    private running;
+    private readonly concurrency;
+    private autoStart;
+    private results;
+    private errors;
+    constructor(options?: QueueOptions);
+    /** Add a task to the queue */
+    add(id: string, fn: () => Promise<T>, priority?: number): void;
+    private process;
+    start(): void;
+    pause(): void;
+    resume(): void;
+    clear(): void;
+    getResult(id: string): T | undefined;
+    getError(id: string): Error | undefined;
+    size(): number;
+    getRunning(): number;
+    isEmpty(): boolean;
+    waitForCompletion(): Promise<void>;
+    getStats(): {
+        pending: number;
+        running: number;
+        completed: number;
+        failed: number;
+    };
+}
+
+/**
+ * StorageManager Class — @mohasinac/core
+ *
+ * Singleton class for managing localStorage and sessionStorage with
+ * namespace prefixing and SSR-safe fallbacks.
+ * Pure utility — no framework or app-specific imports.
+ */
+type StorageType = "local" | "session";
+interface StorageOptions {
+    type?: StorageType;
+    prefix?: string;
+}
+declare class StorageManager {
+    /** Per-prefix instance map — prevents namespace collisions */
+    private static instances;
+    private readonly prefix;
+    private constructor();
+    /**
+     * Get-or-create a StorageManager for the given prefix.
+     * Each prefix returns an independent instance.
+     */
+    static getInstance(prefix?: string): StorageManager;
+    private getStorage;
+    private generateKey;
+    set<T>(key: string, value: T, options?: StorageOptions): boolean;
+    get<T>(key: string, options?: StorageOptions): T | null;
+    remove(key: string, options?: StorageOptions): boolean;
+    clear(options?: StorageOptions): boolean;
+    has(key: string, options?: StorageOptions): boolean;
+    keys(options?: StorageOptions): string[];
+    size(options?: StorageOptions): number;
+    isAvailable(type?: StorageType): boolean;
+    getAll<T = unknown>(options?: StorageOptions): Record<string, T>;
+}
+/** Default StorageManager instance (empty prefix) */
+declare const storageManager: StorageManager;
+
+/**
+ * EventBus Class — @mohasinac/core
+ *
+ * Singleton pub/sub event bus for decoupled communication.
+ * Pure utility — no framework or app-specific imports.
+ */
+type EventCallback = (...args: any[]) => void;
+interface EventSubscription {
+    unsubscribe: () => void;
+}
+declare class EventBus {
+    private static instance;
+    private readonly events;
+    private constructor();
+    static getInstance(): EventBus;
+    on(event: string, callback: EventCallback): EventSubscription;
+    once(event: string, callback: EventCallback): EventSubscription;
+    off(event: string, callback: EventCallback): void;
+    emit(event: string, ...args: any[]): void;
+    removeAllListeners(event?: string): void;
+    listenerCount(event: string): number;
+    eventNames(): string[];
+    hasListeners(event: string): boolean;
+}
+/** Shared singleton instance */
+declare const eventBus: EventBus;
+
+/**
+ * CacheManager Class — @mohasinac/core
+ *
+ * Simple TTL-based in-memory cache with FIFO eviction.
+ * Pure utility — no framework or app-specific imports.
+ */
+interface CacheOptions {
+    ttl?: number;
+}
+interface CacheEntry<T> {
+    value: T;
+    timestamp: number;
+    ttl?: number;
+}
+declare class CacheManager {
+    private static instance;
+    private readonly cache;
+    private readonly maxSize;
+    private constructor();
+    static getInstance(maxSize?: number): CacheManager;
+    set<T>(key: string, value: T, options?: CacheOptions): void;
+    get<T>(key: string): T | null;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    size(): number;
+    keys(): string[];
+    cleanExpired(): number;
+}
+/** Default shared CacheManager singleton */
+declare const cacheManager: CacheManager;
+
+export { type CacheEntry, CacheManager, type CacheOptions, EventBus, type EventSubscription, type LogEntry, type LogLevel, Logger, type LoggerOptions, Queue, type QueueOptions, StorageManager, type StorageOptions, type StorageType, type Task, cacheManager, eventBus, logger, storageManager };