@alwatr/logger - npm Package Compare versions

Comparing version 3.2.14 to 4.0.0

CHANGELOG.md

@@ -6,2 +6,32 @@ # Change Log
 
+## [4.0.0](https://github.com/Alwatr/nanolib/compare/@alwatr/logger@3.2.14...@alwatr/logger@4.0.0) (2024-09-29)
+
+### ⚠ BREAKING CHANGES
+
+* **logger:** logModule renamed to logFileModule
+* **logger:** definePackage and dedupt remove!
+
+### Features
+
+* **logger:** add logStep method to logger ([860aeed](https://github.com/Alwatr/nanolib/commit/860aeedb2da390ee3d47c037b22a37f73e6dbbbc)) by @AliMD
+* use `package-tracer` ([cc3c5f9](https://github.com/Alwatr/nanolib/commit/cc3c5f9c1a3d03f0d81b46835665f16a0426fd0d)) by @mohammadhonarvar
+
+### Bug Fixes
+
+* all dependeny topology ([1c17f34](https://github.com/Alwatr/nanolib/commit/1c17f349adf3e98e2a80ab2da4f0f81028dc9c5f)) by @mohammadhonarvar
+
+### Code Refactoring
+
+* **logger:** remove definePackage from logger ([c8a9d0c](https://github.com/Alwatr/nanolib/commit/c8a9d0cdcc3e45e7a33731ec6ee6a496451e9eb1)) by @mohammadhonarvar
+* **logger:** rename logModule to logFileModule ([1f6bd71](https://github.com/Alwatr/nanolib/commit/1f6bd71272007f5bbc90258ffa13b7d851e0918c)) by @AliMD
+
+### Miscellaneous Chores
+
+* **logger:** change the license to AGPL-3.0 ([4bb4673](https://github.com/Alwatr/nanolib/commit/4bb4673972069a307e799cad9a5078b0288a9340)) by @AliMD
+* Update build and lint scripts ([392d0b7](https://github.com/Alwatr/nanolib/commit/392d0b71f446bce336b0256119a80f07aff794ba)) by @AliMD
+
+### Dependencies update
+
+* bump @types/node ([3d80fed](https://github.com/Alwatr/nanolib/commit/3d80fedaf720af792feb060c2f81c737ebb84e11)) by @dependabot[bot]
+
 ## [3.2.14](https://github.com/Alwatr/nanolib/compare/@alwatr/logger@3.2.13...@alwatr/logger@3.2.14) (2024-09-21)
@@ -8,0 +38,0 @@

dist/main.d.ts

 export * from './logger.js';
-export * from './define-package.js';
 export * from './type.js';
 //# sourceMappingURL=main.d.ts.map

dist/type.d.ts

 /**
- * Represents the AlwatrLogger interface.
- * The AlwatrLogger provides methods for logging various types of information.
+ * Represents the AlwatrLogger interface for logging various types of information at different levels of detail.
+ * This interface allows for structured logging of events, method calls, errors, and more,
+ * aiding in debugging and understanding application behavior.
  */
 export interface AlwatrLogger {
     /**
-     * Debug state for current scope base on localStorage `ALWATR_LOG` pattern.
+     * Indicates whether debug mode is enabled for the current scope.
+     * This state is typically determined based on the `debug` pattern in localStorage.
      */
     debugMode: boolean;
     /**
-     * `console.debug` property change.
+     * Logs a property change with its new value using `console.debug`. Useful for tracking changes in application state.
      *
-     * Example:
+     * @param propertyName The name of the property that has changed.
+     * @param value The new value of the property.
      *
+     * @example
      * ```ts
@@ -19,18 +23,22 @@ * logger.logProperty?.('name', 'ali');
      */
-    logProperty?(property: string, value: unknown): void;
+    logProperty?(propertyName: string, value: unknown): void;
     /**
-     * `console.debug` module name.
+     * Logs the file name of the current module using `console.debug`.
+     * Helpful for identifying the source of log messages.
      *
-     * Example:
+     * @param fileName The name of the file representing the module.
      *
+     * @example
      * ```ts
-     * logger.logModule?.('app');
+     * logger.logFileModule?.('app');
      * ```
      */
-    logModule?(name: string): void;
+    logFileModule?(fileName: string): void;
     /**
-     * `console.debug` function or method calls.
+     * Logs the entry into a function or method using `console.debug`.
+     * Provides a basic trace of program execution.
      *
-     * Example:
+     * @param methodName The name of the function or method being called.
      *
+     * @example
      * ```ts
@@ -42,8 +50,11 @@ * function myMethod () {
      */
-    logMethod?(method: string): void;
+    logMethod?(methodName: string): void;
     /**
-     * `console.debug` function or method calls with arguments.
+     * Logs the entry into a function or method along with its arguments using `console.debug`.
+     * Aids in understanding the context of method calls.
      *
-     * Example:
+     * @param methodName The name of the function or method being called.
+     * @param args An object containing the arguments passed to the method.
      *
+     * @example
      * ```ts
@@ -55,9 +66,34 @@ * function myMethod (a: number, b: number) {
      */
-    logMethodArgs?(method: string, args: unknown): void;
+    logMethodArgs?(methodName: string, args: unknown): void;
     /**
-     * `console.debug` function or method calls with arguments.
+     * Logs specific steps or milestones within a method using `console.debug`.
+     * Facilitates tracking progress within complex functions.
      *
-     * Example:
+     * @param methodName The name of the method where the step occurs.
+     * @param stepName The name or identifier of the specific step.
+     * @param props (Optional) Additional properties or data related to the step.
      *
+     * @example
      * ```ts
+     * function myMethod () {
+     *   logger.logMethod?.('myMethod');
+     *   ...
+     *   logger.logStep?.('myMethod', 'step1');
+     *   ...
+     *   logger.logStep?.('myMethod', 'step2');
+     *   ...
+     * }
+     * ```
+     */
+    logStep?(methodName: string, stepName: string, props?: unknown): void;
+    /**
+     * Logs a complete method call, including its arguments and result, using `console.debug`.
+     * Useful for debugging and understanding the output of functions.
+     *
+     * @param methodName The name of the function or method being called.
+     * @param args An object containing the arguments passed to the method.
+     * @param result The result returned by the method.
+     *
+     * @example
+     * ```ts
      * function add (a: number, b: number): number {
@@ -70,9 +106,11 @@ *   const result = a + b;
      */
-    logMethodFull?(method: string, args: unknown, result: unknown): void;
+    logMethodFull?(methodName: string, args: unknown, result: unknown): void;
     /**
-     * `console.log` an event or expected accident.
-     * not warn or error just important information.
+     * Logs an event or expected incident using `console.log`. Intended for noteworthy information that doesn't represent an error or warning.
      *
-     * Example:
+     * @param methodName The name or context of the event or incident.
+     * @param warningCode A code or identifier for the specific type of event or incident.
+     * @param args Additional details or context related to the event or incident.
      *
+     * @example
      * ```ts
@@ -82,8 +120,12 @@ * logger.incident?.('fetch', 'abort_signal', {url: '/test.json'});
      */
-    incident?(method: string, code: string, ...args: unknown[]): void;
+    incident?(methodName: string, warningCode: string, ...args: unknown[]): void;
     /**
-     * `console.warn` an unexpected accident or error that you handled like warning.
+     * Logs an unexpected incident or handled error as a warning using `console.warn`.
+     * Indicates a potential issue that has been addressed but warrants attention.
      *
-     * Example:
+     * @param methodName The name or context of the incident or error.
+     * @param warningCode A code or identifier for the specific type of incident or error.
+     * @param args Additional details or context related to the incident or error.
      *
+     * @example
      * ```ts
@@ -93,8 +135,11 @@ * logger.accident('fetch', 'file_not_found', {url: '/test.json'});
      */
-    accident(method: string, code: string, ...args: unknown[]): void;
+    accident(methodName: string, warningCode: string, ...args: unknown[]): void;
     /**
-     * `console.error` an unexpected error.
+     * Logs an unexpected error using `console.error`. Highlights critical issues that need to be addressed.
      *
-     * Example:
+     * @param methodName The name or context where the error occurred.
+     * @param errorCode A code or identifier for the specific type of error.
+     * @param args Additional details or context related to the error, including the error object itself.
      *
+     * @example
      * ```ts
@@ -109,8 +154,9 @@ * try {
      */
-    error(method: string, code: string, ...args: unknown[]): void;
+    error(methodName: string, errorCode: string, ...args: unknown[]): void;
     /**
-     * Simple `console.debug` with styled scope.
+     * Performs a simple `console.debug` log with styled scope for general debugging purposes.
      *
-     * Example:
+     * @param args Any number of arguments to be logged.
      *
+     * @example
      * ```ts
@@ -122,6 +168,7 @@ * logger.logOther?.('foo:', 'bar', {a: 1});
     /**
-     * Simple `console.time` with scope.
+     * Starts a timer with a specified label using `console.time`. Useful for measuring performance.
      *
-     * Example:
+     * @param label The label for the timer.
      *
+     * @example
      * ```ts
@@ -133,6 +180,7 @@ * logger.time?.('foo');
     /**
-     * Simple `console.timeEnd` with scope.
+     * Ends a timer with a specified label and logs the elapsed time using `console.timeEnd`.
      *
-     * Example:
+     * @param label The label for the timer.
      *
+     * @example
      * ```ts
@@ -144,6 +192,7 @@ * logger.timeEnd?.('foo');
     /**
-     * log big banner
+     * Logs a prominent banner message, typically used for displaying important announcements or version information.
      *
-     * Example:
+     * @param message The message to be displayed in the banner.
      *
+     * @example
      * ```ts
@@ -150,0 +199,0 @@ * logger.banner('Alwatr PWA v2');

package.json

 {
   "name": "@alwatr/logger",
-  "version": "3.2.14",
+  "version": "4.0.0",
   "description": "Fancy colorful console debugger with custom scope written in tiny TypeScript, ES module.",
@@ -36,3 +36,3 @@ "author": "S. Ali Mihandoost <[e-mail]>",
   },
-  "license": "MIT",
+  "license": "AGPL-3.0-only",
   "files": [
@@ -61,3 +61,3 @@ "**/*.{js,mjs,cjs,map,d.ts,html,md}",
     "d": "yarn run build:es && yarn node --enable-source-maps --trace-warnings",
-    "build": "yarn run build:ts & yarn run build:es",
+    "build": "yarn run build:ts && yarn run build:es",
     "build:es": "nano-build --preset=module",
@@ -71,13 +71,13 @@ "build:ts": "tsc --build",
   "dependencies": {
-    "@alwatr/dedupe": "^1.0.14",
-    "@alwatr/platform-info": "^1.1.13"
+    "@alwatr/package-tracer": "^1.0.0",
+    "@alwatr/platform-info": "^1.2.0"
   },
   "devDependencies": {
-    "@alwatr/nano-build": "^1.3.10",
-    "@alwatr/prettier-config": "^1.0.4",
-    "@alwatr/tsconfig-base": "^1.2.0",
-    "@types/node": "^22.5.5",
+    "@alwatr/nano-build": "^1.4.0",
+    "@alwatr/prettier-config": "^1.0.5",
+    "@alwatr/tsconfig-base": "^1.3.0",
+    "@types/node": "^22.7.4",
     "typescript": "^5.6.2"
   },
-  "gitHead": "6d82461cfdee936b30cbc67473a5a5048773255a"
+  "gitHead": "cc1ea8b688232dcc60e9ebc904ec5566bc25c1ac"
 }

README.md

@@ -1,35 +0,85 @@
-# Logger
+## Logger
 
-Fancy colorful console debugger with custom scope written in tiny TypeScript, ES module.
+A lightweight, flexible, and colorful console logging library for TypeScript and ES modules.
 
-## Example usage
+### Features
 
-```ts
-import {createLogger} from '@alwatr/logger';
+* **Customizable Scopes:** Organize log messages using scopes for easy filtering and debugging.
+* **Colorful Output:** Visually distinguish different log levels and scopes with vibrant colors.
+* **Debug/Development Mode:** Control log verbosity to optimize performance in production environments.
+* **Tiny Footprint:** Minimal overhead, keeping your project lean and efficient.
 
-const logger = createLogger('demo');
+### Installation
 
-function sayHello(name: string) {
-  logger.logMethodArgs?.('sayHello', {name});
+```bash
+npm install @alwatr/logger
+```
+
+### Usage
+
+```typescript
+import { createLogger } from '@alwatr/logger';
+
+const logger = createLogger('my-module'); // Create a logger with a specific scope
+
+function greet(name: string) {
+  logger.logMethodArgs?.('greet', { name }); // Log the method call with its arguments
+  console.log(`Hello, ${name}!`); 
 }
+
+greet('Ali'); 
 ```
 
-### Debug/Develope Mode (DEBUG_MODE)
+### Log Levels and Methods
 
-Many of the methods in the logger are no-ops when the debug mode is off. This is to prevent unnecessary performance impact in production.
+* **`logProperty(propertyName, value)`:** Logs a property change (useful for tracking state).
+* **`logFileModule(fileName)`:** Logs the module's file name for easy identification.
+* **`logMethod(methodName)`:** Logs the entry into a function or method.
+* **`logMethodArgs(methodName, args)`:** Logs a method call with its arguments.
+* **`logStep(methodName, stepName, props?)`:** Logs specific steps within a method.
+* **`logMethodFull(methodName, args, result)`:** Logs a method call with arguments and result.
+* **`incident(methodName, code, ...args)`:** Logs an event or expected incident (informational).
+* **`accident(methodName, code, ...args)`:** Logs an unexpected incident or handled error (warning).
+* **`error(methodName, code, ...args)`:** Logs an unexpected error (critical).
+* **`logOther(...args)`:** General-purpose logging with styled scope.
+* **`time(label)`:** Starts a timer.
+* **`timeEnd(label)`:** Ends a timer and logs the elapsed time.
+* **`banner(message)`:** Logs a large, prominent banner message.
 
+### Enabling Debug Mode
+
 #### Browser
 
-```ts
+1. Open your browser's developer tools.
+2. Go to the "Application" or "Storage" tab.
+3. Find "Local Storage" and locate your application's domain.
+4. Add a new key-value pair: `debug` with the value `1`.
+5. Reload the page.
+
+Or use the following code snippet in the browser console:
+
+```javascript
 window.localStorage?.setItem('debug', '1');
-
-// Please remember to **reload** the window after changing the debug mode.
 ```
 
-> Make sure the [log level](https://developer.chrome.com/docs/devtools/console/log/#browser) in set correctly.
+> **Note:** Ensure the browser console's log level is set to include "Verbose" or "All" to see debug messages.
 
-#### CLI
+#### Node.js
 
-```sh
+```bash
 DEBUG=1 node index.js
 ```
+
+## Sponsors
+
+The following companies, organizations, and individuals support Nitrobase ongoing maintenance and development. Become a Sponsor to get your logo on our README and website.
+
+[![Exir Studio](https://avatars.githubusercontent.com/u/181194967?s=200&v=4)](https://exirstudio.com)
+
+### Contributing
+
+Contributions are welcome! Please read our [contribution guidelines](https://github.com/Alwatr/.github/blob/next/CONTRIBUTING.md) before submitting a pull request.
+
+### License
+
+This project is licensed under the [AGPL-3.0 License](LICENSE).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Copyleft License

License

(Experimental) Copyleft license information was found.

Found 1 instance in 1 package

Mixed license

License

(Experimental) Package contains multiple licenses.

Found 1 instance in 1 package

Non-permissive License

License

(Experimental) A license not known to be considered permissive was found.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

74640

increased by100.36%

Lines of code

238

increased by15.53%

Number of lines in readme file

86

increased by138.89%

Worsened metrics

Number of package files

14

decreased by-12.5%

Number of low license alerts

3

increased byInfinity%

License quality

70

decreased by-30%

Dependency changes

• + Added@alwatr/package-tracer@^1.0.0

• - Removed@alwatr/dedupe@^1.0.14

• - Removed@alwatr/dedupe@1.1.8(transitive)

• - Removed@alwatr/global-this@1.0.3(transitive)

• - Removed@alwatr/polyfill-has-own@1.1.8(transitive)

• Updated@alwatr/platform-info@^1.2.0