@org-quicko/core 1.1.1 → 2.0.0

package/dist/types/src/logger/LoggerFactory.d.ts

@@ -1,19 +1,97 @@
-import winston from 'winston';
-import { LoggingLevel } from '../types/LoggingLevel.js';
+import winston, { LoggerOptions } from 'winston';
 
 /**
- * A factory class for managing logger instances.
- * Provides methods to retrieve and store loggers in a shared storage.
+ * Factory class for creating and managing Winston logger instances.
+ *
+ * @description
+ * Provides a factory for creating Winston logger instances with consistent configuration.
+ * Supports custom logging levels, formats, and transports with a default format pipeline
+ * that includes timestamp, error handling with cause chains, and JSON formatting.
+ *
+ * @example
+ * ```typescript
+ * // Create a logger with custom configuration
+ * const logger = LoggerFactory.createLogger({
+ *   level: 'info',
+ *   transports: [new winston.transports.Console()]
+ * });
+ *
+ * // Create another logger and add a label to it
+ * const apiLogger = LoggerFactory.getLogger('api-service');
+ * apiLogger.info('Server started');
+ * ```
  */
-declare const loggers: Map<string, winston.Logger>;
 declare class LoggerFactory {
     /**
-     * Retrieves a logger instance by its name.
+     * Base logger instance used by the factory.
      *
-     * @param name The name of the logger to retrieve.
-     * @returns The logger instance if found, otherwise `undefined`.
+     * @description
+     * Currently stores a single base logger instance per execution context.
+     * This design can be extended in the future to support multiple base loggers
+     * by replacing this single instance with a Map-based container (similar to Winston's Container API)
+     * to manage multiple named logger configurations.
+     *
+     * @type {winston.Logger}
+     * @private
+     */
+    private static logger;
+    /**
+     * Creates and initializes a new logger instance with the provided configuration.
+     *
+     * @description
+     * Creates a new Winston logger with a consistent default format pipeline that includes
+     * timestamp, error handling with stack traces and cause chains, custom error formatting,
+     * and JSON output. Custom formats are combined with the defaults. If no transports are
+     * specified, defaults to Console transport.
+     *
+     * @param {LoggerOptions} [options] - Optional Winston logger configuration options
+     * @param {LoggingLevel} [options.level='info'] - Logging level (error, warn, info, http, debug, verbose, silly)
+     * @param {winston.LogFormat} [options.format] - Additional custom format to combine with defaults
+     * @param {object} [options.defaultMeta] - Default metadata to include in all log entries from this logger
+     * @param {winston.transport[]} [options.transports] - Transport instances (defaults to Console)
+     *
+     * @returns {winston.Logger} Configured logger instance
+     *
+     * @throws {BaseException} If logger initialization fails
+     *
+     * @example
+     * ```typescript
+     * // Create a logger with custom configuration
+     * const logger = LoggerFactory.createLogger({
+     *   level: 'debug',
+     *   defaultMeta: { service: 'api' },
+     *   transports: [
+     *     new winston.transports.Console(),
+     *     new winston.transports.File({ filename: 'combined.log' })
+     *   ]
+     * });
+     * ```
+     */
+    static createLogger(options?: LoggerOptions): winston.Logger;
+    /**
+     * Gets a logger instance with a label added to the metadata.
+     *
+     * @description
+     * Returns a logger instance that is a child of the base logger with the provided label
+     * added as metadata. Each call creates a new child logger with the specified label.
+     * This is useful for identifying the source of log messages by module or service name.
+     *
+     * @param {string} label - Unique identifier for the logger to include in metadata (e.g., module name, service name)
+     *
+     * @returns {winston.Logger} Child logger instance with the label in metadata
+     *
+     * @example
+     * ```typescript
+     * // Create a logger with a label for the UserService module
+     * const logger = LoggerFactory.getLogger('UserService');
+     *
+     * // Another module can create its own labeled logger
+     * const apiLogger = LoggerFactory.getLogger('APIHandler');
+     *
+     * logger.info('Processing user request'); // Log includes { label: 'UserService' }
+     * ```
      */
-    static createLogger(name: string, level?: LoggingLevel, format?: winston.Logform.Format): winston.Logger;
+    static getLogger(label: string): winston.Logger;
 }
 
-export { LoggerFactory, loggers };
+export { LoggerFactory };

package/dist/types/src/logger/index.d.ts

@@ -1 +1 @@
-export { LoggerFactory, loggers } from './LoggerFactory.js';
+export { LoggerFactory } from './LoggerFactory.js';

package/dist/types/src/utils/date/DateUtil.d.ts

@@ -4,14 +4,14 @@ import { Duration } from 'date-fns';
  * Utility class for date and time operations. Provides methods for parsing,
  * formatting, and performing calculations with dates and times.
  */
-declare class BaseDateUtil {
+declare class DateUtil {
     static readonly ISO_8601_FORMAT = "yyyy-MM-dd'T'HH:mm:ss.SSSxxx";
     /**
      * Gets the current date and time in the specified time zone.
      * @param timeZone The IANA time zone identifier.
      * @returns Current date and time in the specified time zone.
      */
-    protected static now(timeZone: string): Date;
+    static now(timeZone: string): Date;
     /**
      * Gets the current time in milliseconds since the Unix epoch.
      * @returns Current time in milliseconds.
@@ -25,7 +25,7 @@ declare class BaseDateUtil {
      * @throws {IllegalArgumentException} If the date string is invalid.
      * @returns Parsed Date object.
      */
-    protected static readDate(dateString: string, dateFormat: string | undefined, timeZone: string): Date;
+    static readDate(dateString: string, dateFormat: string | undefined, timeZone: string): Date;
     /**
      * Formats a Date or timestamp into a string.
      * @param date The date or timestamp to format.
@@ -33,24 +33,24 @@ declare class BaseDateUtil {
      * @param dateFormat The desired output format (default: ISO_8601_FORMAT).
      * @returns Formatted date string.
      */
-    protected static printDate(date: Date, timeZone: string, dateFormat?: string): string;
-    protected static printDate(date: number, timeZone: string, dateFormat?: string): string;
+    static printDate(date: Date, timeZone: string, dateFormat?: string): string;
+    static printDate(date: number, timeZone: string, dateFormat?: string): string;
     /**
      * Gets the start of the day for a given date or timestamp.
      * @param date The date or timestamp to calculate from.
      * @param timeZone The IANA time zone identifier.
      * @returns The start of the day as a Date object.
      */
-    protected static getStartOfDay(date: Date, timeZone: string): Date;
-    protected static getStartOfDay(date: number, timeZone: string): Date;
+    static getStartOfDay(date: Date, timeZone: string): Date;
+    static getStartOfDay(date: number, timeZone: string): Date;
     /**
      * Gets the end of the day for a given date or timestamp.
      * @param date The date or timestamp to calculate from.
      * @param timeZone The IANA time zone identifier.
      * @returns The end of the day as a Date object.
      */
-    protected static getEndOfDay(date: Date, timeZone: string): Date;
-    protected static getEndOfDay(date: number, timeZone: string): Date;
+    static getEndOfDay(date: Date, timeZone: string): Date;
+    static getEndOfDay(date: number, timeZone: string): Date;
     /**
      * Checks if a date string is valid according to the specified format.
      * @param dateString The date string to validate.
@@ -74,14 +74,6 @@ declare class BaseDateUtil {
  */
     static monthsInBetween(firstDate: Date, secondDate: Date): number;
     static monthsInBetween(firstDate: number, secondDate: number): number;
-    /**
-     * Calculates the absolute number of years between two dates or timestamps.
-     * @param firstDate The first date or timestamp.
-     * @param secondDate The second date or timestamp.
-     * @returns The number of years between the two dates.
-     */
-    static anniversaryYearsInBetween(firstDate: Date, secondDate: Date): number;
-    static anniversaryYearsInBetween(firstDate: number, secondDate: number): number;
     /**
      * Calculates the absolute number of years between two dates or timestamps.
      * @param firstDate The first date or timestamp.
@@ -125,48 +117,5 @@ declare class BaseDateUtil {
      */
     static toMillis(date: Date): number;
 }
-/**
- * Utility class for handling date operations in a fixed time zone.
- * Extends BaseDateUtil with default settings for the 'Asia/Kolkata' time zone.
- */
-declare class DateUtil extends BaseDateUtil {
-    /** Default time zone used for all date operations. */
-    static readonly TIMEZONE = "Asia/Kolkata";
-    /**
-     * Gets the current date and time in the default time zone.
-     * @returns Current date and time as a Date object.
-     */
-    static now(): Date;
-    /**
-     * Parses a date string into a Date object using the default time zone.
-     * @param dateString The date string to parse.
-     * @param dateFormat Optional format of the date string (default: ISO_8601_FORMAT).
-     * @throws {IllegalArgumentException} If the date string is invalid.
-     * @returns Parsed Date object.
-     */
-    static readDate(dateString: string, dateFormat?: string): Date;
-    /**
-     * Formats a Date or timestamp into a string using the default time zone.
-     * @param date The date or timestamp to format.
-     * @param dateFormat Optional desired output format (default: ISO_8601_FORMAT).
-     * @returns Formatted date string.
-     */
-    static printDate(date: Date, dateFormat?: string): string;
-    static printDate(date: number, dateFormat?: string): string;
-    /**
-     * Gets the start of the day for a given date or timestamp using the default time zone.
-     * @param date The date or timestamp to calculate from.
-     * @returns A Date object representing the start of the day.
-     */
-    static getStartOfDay(date: Date): Date;
-    static getStartOfDay(date: number): Date;
-    /**
-     * Gets the end of the day for a given date or timestamp using the default time zone.
-     * @param date The date or timestamp to calculate from.
-     * @returns A Date object representing the end of the day.
-     */
-    static getEndOfDay(date: Date): Date;
-    static getEndOfDay(date: number): Date;
-}
 
 export { DateUtil };

package/package.json

@@ -1,136 +1,140 @@
-{
-  "name": "@org-quicko/core",
-  "version": "1.1.1",
-  "description": "A library in typescript for common entities and utilities across Quicko",
-  "author": "Quicko",
-  "main": "dist/cjs/build/node/index.cjs",
-  "module": "dist/esm/build/node/index.js",
-  "browser": "dist/browser/build/browser/index.js",
-  "types": "dist/types/index.d.ts",
-  "type": "module",
-  "scripts": {
-    "clean": "rm -rf dist && npm cache clean --force",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "prebuild": "npm run clean && npm run lint",
-    "build": "rollup -c"
-  },
-  "license": "ISC",
-  "files": [
-    "dist/**/*"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/types/index.d.ts",
-      "node": {
-        "import": "./dist/esm/build/node/index.js",
-        "require": "./dist/cjs/build/node/index.cjs"
-      },
-      "default": "./dist/browser/build/browser/index.js"
-    },
-    "./beans": {
-      "types": "./dist/types/src/beans/index.d.ts",
-      "node": {
-        "import": "./dist/esm/beans/index.js",
-        "require": "./dist/cjs/beans/index.cjs"
-      },
-      "default": "./dist/browser/beans/index.js"
-    },
-    "./types": {
-      "types": "./dist/types/src/types/index.d.ts",
-      "node": {
-        "import": "./dist/esm/types/index.js",
-        "require": "./dist/cjs/types/index.cjs"
-      },
-      "default": "./dist/browser/types/index.js"
-    },
-    "./utils": {
-      "types": "./dist/types/src/utils/index.d.ts",
-      "node": {
-        "import": "./dist/esm/utils/index.js",
-        "require": "./dist/cjs/utils/index.cjs"
-      },
-      "default": "./dist/browser/utils/index.js"
-    },
-    "./utils/date": {
-      "types": "./dist/types/src/utils/date/index.d.ts",
-      "node": {
-        "import": "./dist/esm/utils/date/index.js",
-        "require": "./dist/cjs/utils/date/index.cjs"
-      },
-      "default": "./dist/browser/utils/date/index.js"
-    },
-    "./logger": {
-      "types": "./dist/types/src/logger/index.d.ts",
-      "node": {
-        "import": "./dist/esm/logger/index.js",
-        "require": "./dist/cjs/logger/index.cjs"
-      }
-    },
-    "./exceptions": {
-      "types": "./dist/types/src/exceptions/index.d.ts",
-      "node": {
-        "import": "./dist/esm/exceptions/index.js",
-        "require": "./dist/cjs/exceptions/index.cjs"
-      },
-      "default": "./dist/browser/exceptions/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "typesVersions": {
-    "*": {
-      "*": [
-        "dist/types/*"
-      ],
-      "beans": [
-        "dist/types/src/beans/index.d.ts"
-      ],
-      "types": [
-        "dist/types/src/types/index.d.ts"
-      ],
-      "utils": [
-        "dist/types/src/utils/index.d.ts"
-      ],
-      "utils/date": [
-        "dist/types/src/utils/date/index.d.ts"
-      ],
-      "exceptions": [
-        "dist/types/src/exceptions/index.d.ts"
-      ],
-      "logger": [
-        "dist/types/src/logger/index.d.ts"
-      ]
-    }
-  },
-  "directories": {
-    "lib": "./dist"
-  },
-  "engines": {
-    "node": ">=14"
-  },
-  "dependencies": {
-    "@date-fns/tz": "^1.1.2",
-    "class-transformer": "^0.5.1",
-    "class-validator": "^0.14.1",
-    "date-fns": "^4.1.0",
-    "tslib": "^2.8.1",
-    "winston": "^3.17.0"
-  },
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^28.0.3",
-    "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-typescript": "^12.1.2",
-    "@types/node": "^22.7.0",
-    "@typescript-eslint/eslint-plugin": "^8.33.1",
-    "@typescript-eslint/parser": "^8.33.1",
-    "esbuild-plugin-eslint": "^0.3.7",
-    "eslint": "^9.28.0",
-    "eslint-config-prettier": "^10.1.5",
-    "eslint-import-resolver-typescript": "^3.7.0",
-    "glob": "^11.0.2",
-    "rollup": "^4.40.2",
-    "rollup-plugin-dts": "^6.2.1",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.6.2"
-  }
-}
+{
+	"name": "@org-quicko/core",
+	"version": "2.0.0",
+	"description": "A library in typescript for common entities and utilities across Quicko",
+	"author": "Quicko",
+	"main": "dist/cjs/build/node/index.cjs",
+	"module": "dist/esm/build/node/index.js",
+	"browser": "dist/browser/build/browser/index.js",
+	"types": "dist/types/index.d.ts",
+	"type": "module",
+	"scripts": {
+		"clean": "rm -rf dist && npm cache clean --force",
+		"lint": "eslint .",
+		"lint:fix": "eslint . --fix",
+		"prebuild": "npm run clean && npm run lint",
+		"build": "rollup -c",
+		"test:date:util": "set NODE_ENV=local && node --experimental-vm-modules node_modules/jest/bin/jest.js run ./tests/DateUtil.test.ts"
+	},
+	"license": "ISC",
+	"files": [
+		"dist/**/*"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"node": {
+				"import": "./dist/esm/build/node/index.js",
+				"require": "./dist/cjs/build/node/index.cjs"
+			},
+			"default": "./dist/browser/build/browser/index.js"
+		},
+		"./beans": {
+			"types": "./dist/types/src/beans/index.d.ts",
+			"node": {
+				"import": "./dist/esm/beans/index.js",
+				"require": "./dist/cjs/beans/index.cjs"
+			},
+			"default": "./dist/browser/beans/index.js"
+		},
+		"./types": {
+			"types": "./dist/types/src/types/index.d.ts",
+			"node": {
+				"import": "./dist/esm/types/index.js",
+				"require": "./dist/cjs/types/index.cjs"
+			},
+			"default": "./dist/browser/types/index.js"
+		},
+		"./utils": {
+			"types": "./dist/types/src/utils/index.d.ts",
+			"node": {
+				"import": "./dist/esm/utils/index.js",
+				"require": "./dist/cjs/utils/index.cjs"
+			},
+			"default": "./dist/browser/utils/index.js"
+		},
+		"./utils/date": {
+			"types": "./dist/types/src/utils/date/index.d.ts",
+			"node": {
+				"import": "./dist/esm/utils/date/index.js",
+				"require": "./dist/cjs/utils/date/index.cjs"
+			},
+			"default": "./dist/browser/utils/date/index.js"
+		},
+		"./logger": {
+			"types": "./dist/types/src/logger/index.d.ts",
+			"node": {
+				"import": "./dist/esm/logger/index.js",
+				"require": "./dist/cjs/logger/index.cjs"
+			}
+		},
+		"./exceptions": {
+			"types": "./dist/types/src/exceptions/index.d.ts",
+			"node": {
+				"import": "./dist/esm/exceptions/index.js",
+				"require": "./dist/cjs/exceptions/index.cjs"
+			},
+			"default": "./dist/browser/exceptions/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"typesVersions": {
+		"*": {
+			"*": [
+				"dist/types/*"
+			],
+			"beans": [
+				"dist/types/src/beans/index.d.ts"
+			],
+			"types": [
+				"dist/types/src/types/index.d.ts"
+			],
+			"utils": [
+				"dist/types/src/utils/index.d.ts"
+			],
+			"utils/date": [
+				"dist/types/src/utils/date/index.d.ts"
+			],
+			"exceptions": [
+				"dist/types/src/exceptions/index.d.ts"
+			],
+			"logger": [
+				"dist/types/src/logger/index.d.ts"
+			]
+		}
+	},
+	"directories": {
+		"lib": "./dist"
+	},
+	"engines": {
+		"node": ">=14"
+	},
+	"dependencies": {
+		"@date-fns/tz": "^1.1.2",
+		"class-transformer": "^0.5.1",
+		"class-validator": "^0.14.1",
+		"date-fns": "^4.1.0",
+		"tslib": "^2.8.1",
+		"winston": "^3.17.0"
+	},
+	"devDependencies": {
+		"@rollup/plugin-commonjs": "^28.0.3",
+		"@rollup/plugin-node-resolve": "^16.0.1",
+		"@rollup/plugin-typescript": "^12.1.2",
+		"@types/node": "^22.7.0",
+		"@typescript-eslint/eslint-plugin": "^8.33.1",
+		"@typescript-eslint/parser": "^8.33.1",
+		"esbuild-plugin-eslint": "^0.3.7",
+		"eslint": "^9.28.0",
+		"eslint-config-prettier": "^10.1.5",
+		"eslint-import-resolver-typescript": "^3.7.0",
+		"glob": "^11.0.2",
+		"rollup": "^4.40.2",
+		"rollup-plugin-dts": "^6.2.1",
+		"ts-node": "^10.9.2",
+		"typescript": "^5.6.2",
+		"@types/jest": "^29.5.12",
+		"jest": "^29.7.0",
+		"ts-jest": "^29.2.5"
+	}
+}