sweet-error 1.0.1 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [2.0.0] - 2025-12-24
+
+### Added
+
+- New configuration option: `autoExit` to control process termination.
+- New configuration option `locationStyle` for additional output formats.
+- Exported shared types from `types.ts`
+
+### Changed
+
+- Improved JSDoc documentation.
+- Refined console rendering to avoid unnecessary blank lines of missing optional properties.
+
+### Removed
+
+- Removed the `options` instance property.
+- Removed the `logger` instance property.
+- Renamed `SweetErrorOptions` to `Config`.
+- Removed named export `SweetError`, the package now uses a default export.
+
+### Migration Notes
+
+- The `error.options` property has been removed.
+  Replace any usage of `error.options` with the corresponding instance properties
+  (e.g. `error.autoExit`, `error.locationStyle`, `error.colorize`).
+
+- The `logger` function is no longer exposed as an instance property.
+  Custom logging logic must be provided through the configuration object at initialization.
+
+- Update TypeScript imports from `SweetErrorOptions` to `ErrorConfig`
+
+- Update imports to use the default export instead of a named export.
+
+## [1.0.1] - 2025-06-7
+
+### Added
+
+- Initial release of `sweet-error`

package/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+Contributions are welcome in all forms.
+
+You can help by:
+- Opening new issues for bugs, questions, or feature requests
+- Suggesting improvements to documentation or API design
+
+If you’re unsure whether something is worth reporting, feel free to open an issue and start a discussion.

package/README.md

@@ -2,6 +2,15 @@
 
 Makes nodeJs Error cleaner, more readable and better formatted
 
+- [SweetError](#sweeterror)
+  - [Installation](#installation)
+  - [Example usage](#example-usage)
+  - [Api reference](#api-reference)
+    - [Configuration Properties](#configuration-properties)
+    - [Instance properties](#instance-properties)
+  - [License](#license)
+  - [Changelog](#changelog)
+
 ## Installation
 
 #### NodeJs
@@ -10,13 +19,13 @@ Makes nodeJs Error cleaner, more readable and better formatted
 npm install sweet-error
 ```
 
-## Example
+## Example usage
 
 ```js
 // cjs
-const { SweetError } = require('sweet-error');
+const SweetError = require('sweet-error');
 // mjs
-import { SweetError } from 'sweet-error';
+import SweetError from 'sweet-error';
 
 new SweetError(
   [
@@ -35,81 +44,235 @@ new SweetError(
 <br />
 
 <div align='center'>
-  <img src="./sweet-error.png" style='border-radius: 10px'></img>
+  <img src="./screenshots/sweet-error.png" style='border-radius: 10px'></img>
 </div>
 
-## Api
+## Api reference
+
+### `new SweetError(messages, [config])`
+
+Creates a new `SweetError` instance.
+
+**Parameters**:
+
+- `messages` — An array of messages, where each message can be of any data type, and each index in the array represents a line.
+
+  - **Required**
+  - **Type:** `any[]`
+
+- `config` — Optional configuration object, see [configuration properties](#configuration-properties)
+
+  - **Optional**
+  - **Type:** `Object`
+
+## Configuration Properties
+
+### `name`
+
+Sets the name of the current error instance.
+
+This is typically used to identify the type of error when logging or displaying it in the console.
+
+- **Optional**
+- **Type:** `string`
+- **Default:** `undefined`
+
+### `code`
+
+Sets the current instance error code.
+
+This can be used to programmatically identify or handle specific error types.
+
+- **Optional**
+- **Type:** `string`
+- **Default:** `undefined`
+
+**Example** :
 
 ```js
-const error = new SweetError(messages, [options]);
+new SweetError(['ACCESERR Error!'], {
+  code: 'ACCESERR',
+});
 ```
 
-### messages
+### `exitCode`
 
-**required**
-Type: `any[]`  
-An array of messages, where each message can be of any data type, and each index in the array represents a line.
+Sets the code or signal name used to terminate the Node.js process when the instance triggers an exit.
 
-### options
+- **Optional**
+- **Type:** `number | string`
+- **Default:** `undefined`
 
-- **name**  
-  Type: `string`  
-  The string represents the instance name e.g: `SomeError`
+### `autoExit`
 
-- **code**  
-  Type: `string`  
-  The string represents the instance code e.g: `SomeError.SomethingWrong`
+Controls whether the Node.js process should automatically exit after the error is logged.
 
-- **exitCode**  
-  Type: `string | number`  
-  The code to exit the `node.js` process with
+Set this to `true` to terminate the process immediately after logging, or `false` to continue running and handle termination manually.
 
-- **colorize**  
-  Type: `boolean`  
-  Default: `true`  
-  Enables or disables text colorization
+- **Optional**
+- **Type:** `boolean`
+- **Default:** `true`
 
-- **logger**  
-  Type: `function`  
-  The function that controls how the Error appears and how its parts are arranged, with some helpful utils that the `SweetError` uses internally
+**Example** :
 
-### error.messages
+```js
+new SweetError({
+  autoExit: false,
+});
+
+console.log('The process will NOT exit automatically');
+```
+
+### `colorize`
+
+Enables or disables text colorization in the console output.
+
+When set to `true`, the error messages will include colors for better readability.  
+When `false`, all output will be plain text.
+
+- **Optional**
+- **Type:** `boolean`
+- **Default:** `true`
+
+### `locationStyle`
+
+Determines how the error location (file, line, column) is formatted when displayed in the console.
 
-Type: `any[]`  
-Returns the specified messages array that is used to initialize the instance
+This allows customization of the visual style of the location information for improved readability.
 
-### error.options
+- **Optional**
+- **Type:** `LocationStyle`
+- **Default:** `'label'`
 
-Type: `SweetErrorOptions | undefined`  
-Returns the options object that the instance initialized with
+**Example** :
 
-### error.name
+- `locationStyle: label` — For readable, human-friendly format.
 
-Type: `string | undefined`  
-Returns the instance name
+![locationStyle: label](./screenshots/location-style-label.png)
 
-### error.code
+- `locationStyle: coords` — Clickable links for IDEs / Standard IDE format.
 
-Type: `string | undefined`  
-Returns the instance code of the error
+![locationStyle: coords](./screenshots/location-style-coords.png)
 
-### error.exitCode
+- `locationStyle: full` — For most formal and complete format.
+
+![locationStyle: full](./screenshots/location-style-full.png)
+
+### `logger`
+
+A custom function to control how the `SweetError` output is rendered.  
+This function is provided via the configuration object when creating a new instance.
+
+You can override this function to implement custom logging behavior, such as formatting output differently, or integrating with other logging systems.
+
+- **Optional**
+- **Type:** `(this: SweetError) => void`
+
+**Example:**
+
+```js
+new SweetError(['Custom output!'], {
+  logger() {
+    console.log(this.func.colorize('Custom error message'));
+  },
+});
+```
 
-Type: `string | number | undefined`  
-Returns the instance exit code that was used to exit the runtime.
+## Instance properties
 
-### error.stack
+### `.messages`
 
-Type: `any[]`  
-Returns an array of objects representing the captured instance stack.
+An array of messages used to initialize the error instance.
 
-### error.func
+- **Type:** `any[]`
 
-Type: `Function[]`  
-Returns an array of utility functions used internally to customize error output. These functions can also be destructured from this within the logger function in the instance's options object.
+### `.name`
 
-<h4 align='center'>Please Hit the ⭐ button if you found this useful</h4>
+The name of the error instance.
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+### `.code`
+
+The error code associated with this instance.
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+### `.exitCode`
+
+The code or signal name used to terminate the Node.js process.
+
+- **Type:** `number | string`
+- **Default:** `undefined`
+
+### `.autoExit`
+
+Indicates whether the `SweetError` instance is configured to automatically exit the Node.js process after logging.
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+### `.locationStyle`
+
+Indicates how the error location (file, line, column) is formatted for this `SweetError` instance when rendered in the console.
+
+- **Type:** `LocationStyle`
+- **Default:** `'label'`
+
+### `.colorize`
+
+Indicates whether the `SweetError` instance will render messages with color in the console.
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+### `.stack`
+
+The stack trace captured by the `SweetError` instance at the time of creation.
+
+- **Type:** `StackData[]`
+- **Readonly**
+
+### `.func`
+
+A read-only collection of string formatting and transformation utilities available on the `SweetError` instance.
+
+These utilities are primarily intended for use **inside a custom `logger` function** to help customize the format and appearance of the error output.
+
+- **Readonly**
+
+#### Utilities
+
+- `colorize(sentence: string): string`  
+  Applies random terminal colors to each word in a sentence using ANSI codes.
+
+- `format(object: any): string`  
+  Serializes an object into a JSON5-formatted string for pretty printing.
+
+- `indent(string: string, padding: number): string`  
+  Prepends a specific number of spaces to every line in a multiline string.
+
+- `wrap(text: string, width: number): string`  
+  Breaks a long string into multiple lines based on the specified character width.
+
+**Example** :
+
+```js
+new SweetError(['Error Occurred!'], {
+  logger() {
+    const { wrap } = this.func;
+
+    console.log(wrap('This is a long message that will be wrapped', 40));
+  },
+});
+```
 
 ## License
 
-[MIT License ©](./LICENSE)
+This project is licensed under the MIT License — see the [LICENSE](./LICENSE) file for details.
+
+## Changelog
+
+See the [CHANGELOG](./CHANGELOG.md) for a detailed history of all changes, versions, and releases.

package/dist/SweetError.d.ts

@@ -0,0 +1,154 @@
+import { StackData } from '../node_modules/@types/stack-utils';
+
+interface ErrorConfig {
+    /**
+     * The instance name e.g `SomeError`
+     *
+     * @default undefined
+     * */
+    name?: string;
+    /**
+     * The instance error code e.g `SomeError.SomethingWrong`
+     *
+     * @default undefined
+     * */
+    code?: string;
+    /**
+     * The exit code or signal name used when the Node process terminates.
+     *
+     * @default 0
+     * */
+    exitCode?: string | number;
+    /**
+     * Whether to automatically terminate the process after logging.
+     *
+     * @default true
+     */
+    autoExit?: boolean;
+    /**
+     * Enables or disables text colorization
+     *
+     * @default true
+     * */
+    colorize?: boolean;
+    /**
+     * Determines how line and column information is displayed:
+     * - `label`: For readable, human-friendly format.
+     *   > `line: 3 column: 1 file: index.ts`
+     * - `coords`: Clickable links for IDEs / Standard IDE format.
+     *   > `file: index.ts:3:1`
+     * - `full`: For most formal and complete format.
+     *   > `line: 3 column: 1 file: index.ts:3:1`
+     *
+     * @default 'label'
+     */
+    locationStyle?: LocationStyle;
+    /** Controls how should `SweetError` output looks and organized */
+    logger?: (this: SweetError) => void;
+}
+/**
+ * Determines how line and column information is displayed:
+ * - `label`: For readable, human-friendly format.
+ *   > `line: 3 column: 1 file: index.ts`
+ * - `coords`: Clickable links for IDEs / Standard IDE format.
+ *   > `file: index.ts:3:1`
+ * - `full`: For most formal and complete format.
+ *   > `line: 3 column: 1 file: index.ts:3:1`
+ */
+type LocationStyle = 'label' | 'coords' | 'full';
+
+declare class SweetError {
+    /** An array of messages, each index represents a line */
+    messages: any[];
+    /**
+     * The instance name e.g., `SomeError`
+     *
+     * @default undefined
+     * */
+    name?: string;
+    /**
+     * The instance code e.g., `SomeError.SomethingWrong`
+     *
+     * @default undefined
+     * */
+    code?: string;
+    /**
+     * The exit code or signal name used when the Node process terminates.
+     *
+     * @default undefined
+     * */
+    exitCode?: number | string;
+    /**
+     * Whether to automatically terminate the process after logging.
+     *
+     * @default true
+     */
+    autoExit: boolean;
+    /**
+     * Determines how line and column information is displayed:
+     * - `label`: For readable, human-friendly format.
+     *   > `line: 3 column: 1 file: index.ts`
+     * - `coords`: Clickable links for IDEs / Standard IDE format.
+     *   > `file: index.ts:3:1`
+     * - `full`: For most formal and complete format.
+     *   > `line: 3 column: 1 file: index.ts:3:1`
+     *
+     * @default 'label'
+     */
+    locationStyle: LocationStyle;
+    /**
+     * Enables or disables text colorization
+     *
+     * @default true
+     * */
+    colorize: boolean;
+    /**
+     * The instance captured stack.
+     *
+     * @readonly
+     * */
+    readonly stack: StackData[];
+    /**
+     * A collection of string formatting and transformation utilities.
+     *
+     * @readonly
+     * */
+    readonly func: {
+        /**
+         * Applies random terminal colors to each word in a sentence.
+         *
+         * @param {string} sentence - The string to colorize.
+         * @returns {string} The colorized string with ANSI codes.
+         */
+        colorize: (sentence: string) => string;
+        /**
+         * Serializes an object into a JSON5 formatted string.
+         *
+         * @param {any} object - The object to stringify.
+         * @returns {string} The formatted JSON5 string.
+         */
+        format: (object: any) => string;
+        /**
+         * Prepends a specific number of spaces to every line in a string.
+         *
+         * @param {string} string - The multiline string to indent.
+         * @param {number} padding - The number of spaces to add.
+         * @returns {string}
+         */
+        indent: (string: string, padding: number) => string;
+        /**
+         * Breaks a long string into multiple lines based on character width.
+         *
+         * @param {string} text - The text to wrap.
+         * @param {number} width - The maximum line length.
+         * @returns {string}
+         */
+        wrap: (text: string, width: number) => string;
+    };
+    /**
+     * Creates a new `SweetError` instance.
+     */
+    constructor(messages: any[], config?: ErrorConfig);
+}
+
+export { type ErrorConfig, type LocationStyle, SweetError as default };