@limitless.claver/stringify - npm Package Compare versions

Comparing version 1.0.2 to 1.0.3

package.json

@@ -7,3 +7,3 @@ {
   },
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "String helper method for all string and JSON manipulations",
@@ -27,11 +27,10 @@ "main": "./dist/index.js",
   "devDependencies": {
-    "@types/node": "^18.14.2",
+    "@types/node": "^18.15.8",
     "jest": "^29.5.0",
-    "nodemon": "^2.0.21",
+    "nodemon": "^2.0.22",
     "typescript": "^4.9.5"
   },
   "dependencies": {
-    "@limitless.claver/stringify": "^1.0.0",
     "dotenv": "^16.0.3"
   }
 }

README.md

 # Stringify
-The javascript string manipulation library
+
+Stringify provides a set of methods for working with JSON strings and objects, case conversion, as well as encryption and decryption capabilities. It extends the Ncrypt class for encryption and decryption, and also allows you to convert JSON strings to JSON objects, and vice versa.
+
+In this library, you'll find a variety of string conversion methods such as converting strings to camel case, snake case, kebab case, and sentence case. You can also encrypt and decrypt strings using the encryption key provided or via the .env file.
+
+This documentation provides an overview of the Stringify class, including its methods, parameters, return types, and examples of how to use them. Whether you're working on a small or large project, Stringify aims to provide an easy-to-use set of tools that can help you with common string manipulation tasks.
+
+## Installation
+
+To use Stringify, you need to have Node.js installed on your computer. Once you have Node.js installed, you can install the package using the following command in your terminal:
+
+```
+npm install @limitless-kode/stringify
+```
+
+### Create a `.env` file
+
+Add a `32 character` length encryption key to the created `.env` file. You can ignore this step if you do not intend to use the encryption methods of this library.
+
+```
+//.env
+ENCRYPTION_KEY=6bef904c684547d18f15a47e09ecdbb3
+```
+
+## Usage
+
+### **Encryption and Decryption Methods**
+
+### **`toEncryptedString(value: any): string`**
+
+Encrypts a string using the encryption key.
+
+### **Example**
+
+```jsx
+const plaintext = 'my secret message';
+const encrypted = Stringify.toEncryptedString(plaintext);
+console.log(encrypted); // Encrypted string
+```
+
+### **Parameters**
+
+- **`value`**: The string to encrypt.
+
+### **Returns**
+
+- The encrypted string.
+
+### **`toDecryptedString(value: string): string`**
+
+Decrypts an encrypted string to plain text using the encryption key.
+
+### **Example**
+
+```jsx
+const encrypted = 'Encrypted string';
+const plaintext = Stringify.toDecryptedString(encrypted);
+console.log(plaintext); // 'my secret message'
+```
+
+### **Parameters**
+
+- **`value`**: The encrypted string.
+
+### **Returns**
+
+- The decrypted string.
+
+### **`toDecryptedJSON(value: string): any`**
+
+Decrypts an encrypted string to a JSON object using the encryption key.
+
+### **Example**
+
+```jsx
+const encrypted = 'Encrypted JSON string';
+const jsonObject = Stringify.toDecryptedJSON(encrypted);
+console.log(jsonObject); // Decrypted JSON object
+```
+
+### **Parameters**
+
+- **`value`**: The encrypted JSON string.
+
+### **Returns**
+
+- The decrypted JSON object.
+
+### **String Formatting Methods**
+
+### **`formatString(template: string, values: Record<string, any>): string`**
+
+The **`formatString`** method replaces placeholders in a string template with values from an object.
+
+### **Parameters**
+
+- **`template`** (required) - The string template with placeholders to replace.
+- **`values`** (required) - The object containing the values to use for replacement.
+
+### **Example**
+
+```jsx
+const template = 'Hello, ${firstName} ${lastName}!';
+const values = { firstName: 'John', lastName: 'Doe' };
+const formattedString = Stringify.formatString(template, values);
+console.log(formattedString);
+// Output: "Hello, John Doe!"
+```
+
+### **`padLeft(str: string, length: number, paddingChar: string = " "): string`**
+
+The **`padLeft`** method pads a string on the left with a specified character until it reaches the desired length.
+
+### **Parameters**
+
+- **`str`** (required) - The string to pad.
+- **`length`** (required) - The length to which the string should be padded.
+- **`paddingChar`** (optional) - The character to use for padding. The default value is a space character.
+
+### **Example**
+
+```jsx
+const str = '123';
+const paddedString = Stringify.padLeft(str, 5, '0');
+console.log(paddedString);
+// Output: "00123"
+```
+
+### **`padRight(str: string, length: number, paddingChar: string = " "): string`**
+
+The **`padRight`** method pads a string on the right with a specified character until it reaches the desired length.
+
+### **Parameters**
+
+- **`str`** (required) - The string to pad.
+- **`length`** (required) - The length to which the string should be padded.
+- **`paddingChar`** (optional) - The character to use for padding. The default value is a space character.
+
+### **Example**
+
+```jsx
+const str = '123';
+const paddedString = Stringify.padRight(str, 5, '0');
+console.log(paddedString);
+// Output: "12300"
+```
+
+### **`truncate(str: string, maxLength: number, suffix: string = "..."): string`**
+
+The **`truncate`** method truncates a string to a specified maximum length and appends a suffix to the end of the string.
+
+### **Parameters**
+
+- **`str`** (required) - The string to truncate.
+- **`maxLength`** (required) - The maximum length of the truncated string.
+- **`suffix`** (optional) - The suffix to append to the end of the string if it is truncated. The default value is "...".
+
+### **Example**
+
+```jsx
+const str = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ut perspiciatis unde omnis iste natus error sit voluptatem';
+const truncatedString = Stringify.truncate(str, 50);
+console.log(truncatedString);
+// Output: "Lorem ipsum dolor sit amet, consectetur adipisc..."
+
+const str = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ut perspiciatis unde omnis iste natus error sit voluptatem';
+const truncatedString = Stringify.truncate(str, 50, "(continue)");
+console.log(truncatedString);
+// Output: "Lorem ipsum dolor sit amet, consectetur adipisc (continue)"
+```
+
+### **String Case Conversion Methods**
+
+### **`toTitleCase(str: string): string`**
+
+Converts the first letter of each word in a given string to uppercase and the remaining letters to lowercase.
+
+### Example
+
+```jsx
+Stringify.toTitleCase("example sentence"); // "Example Sentence"
+```
+
+### Parameters
+
+- **`str`**: The string to convert to title case.
+
+### Returns
+
+- A string that has been converted to title case.
+
+### **`toUpperCase(str: string): string`**
+
+Converts all letters in a given string to uppercase.
+
+### Example
+
+```jsx
+Stringify.toUpperCase("example sentence"); // "EXAMPLE SENTENCE"
+```
+
+### Parameters
+
+- **`str`**: The string to convert to uppercase.
+
+### Returns
+
+- A string that has been converted to uppercase.
+
+### **`toLowerCase(str: string): string`**
+
+Converts all letters in a given string to lowercase.
+
+### Example
+
+```jsx
+Stringify.toLowerCase("Example Sentence"); // "example sentence"
+```
+
+### Parameters
+
+- **`str`**: The string to convert to lowercase.
+
+### Returns
+
+- A string that has been converted to lowercase.
+
+### URL Encoding **Methods**
+
+### **`encodeQueryString(params: Record<string, any>): string`**
+
+Encodes an object of key-value pairs as a URL query string.
+
+### Example
+
+```jsx
+Stringify.encodeQueryString({ foo: 'bar', baz: 'qux' }); // "foo=bar&baz=qux"
+```
+
+### Parameters
+
+- **`params`**: An object containing key-value pairs to be encoded.
+
+### Returns
+
+- A string containing the encoded key-value pairs as a query string.
+
+### **`decodeQueryString(queryString: string): Record<string, any>`**
+
+Decodes a URL query string into an object of key-value pairs.
+
+### Example
+
+```jsx
+Stringify.decodeQueryString("foo=bar&baz=qux"); // { foo: 'bar', baz: 'qux' }
+```
+
+### Parameters
+
+- **`queryString`**: A string containing the encoded key-value pairs as a query string.
+
+### Returns
+
+- An object containing the decoded key-value pairs.
+
+### **`parseUrl(url: string): Record<string, any>`**
+
+Parses a URL into an object containing its protocol, hostname, port, and pathname, as well as any query parameters.
+
+### Example
+
+```jsx
+Stringify.parseUrl("https://www.example.com/search?q=example");
+// { protocol: 'https:', hostname: 'www.example.com', port: '', pathname: '/search', q: 'example' }
+```
+
+### Parameters
+
+- **`url`**: The URL to be parsed.
+
+### Returns
+
+- An object containing the parsed URL properties.
+
+## Options
+
+### 🔨 **JSON Manipulation**
+
+- ***`toJson`***: Converts a JSON string to a JSON Object
+- ***`toString`***: Converts a JSON object to a string using **`JSON.stringify`**
+
+### **🔐 Encryption and Decryption**
+
+Before you can use these methods, please add a **`.env`** file with a **`32 alpha numeric string`** as an **`ENCRYPTION_KEY`**.
+
+- ***`toEncryptedString`**:* Encrypts and returns an encrypted hash of any string passed to it.
+- ***`toDecryptedString`**:* Decrypts the encrypted string and returns the original text.
+- ***`toDecryptedJSON`**:* Decrypts an encrypted stringified JSON object and returns the original JSON object.
+
+### 🅰️ **Case Conversions**
+
+- ***`toCamelCase`**:* Converts a string to camel case.
+- ***`toSnakeCase`**:* Converts a string to snake case.
+- ***`toKebabCase`**:* Converts a string to kebab case.
+- ***`toSentenceCase`**:* Converts a string to sentence case.
+- ***`toTitleCase`**:* Converts a string to title case.
+- ***`toUpperCase`**:* Converts a string to uppercase.
+- ***`toLowerCase`**:* Converts a string to lowercase.
+
+### 🔗 **URL Encoding**
+
+- ***`encodeQueryString`**:* Encodes a query string.
+- ***`decodeQueryString`**:* Decodes a query string.
+- ***`parseUrl`**:* Parses a URL.
+
+### ⛓️ **String Formatting**
+
+- ***`formatString`**:* Formats a string with placeholders and values.
+- ***`padLeft`**:* Pads a string with characters on the left.
+- ***`padRight`**:* Pads a string with characters on the right.
+- ***`truncate`**:* Truncates a string to a specified length.

src/stringify.ts

 import Ncrypt from './ncrypt';
 
 require('dotenv').config();
+
+/**
+ * The Stringify class provides a set of utility methods for working with strings.
+ * It extends the Ncrypt class for encryption and decryption capabilities.
+ */
 export default class Stringify extends Ncrypt{
@@ -10,4 +15,9 @@ constructor(key?: string) {
   /**
-   * Converts JSON string to a JSON Object
-   * @param value
+   * Converts a JSON string to a JSON Object
+   * @param value - A JSON string
+   * @returns - A JSON Object
+   * @example
+   * const jsonString = '{"name":"John","age":30,"city":"New York"}';
+   * const jsonObject = Stringify.toJson(jsonString);
+   * console.log(jsonObject); // { name: 'John', age: 30, city: 'New York' }
    */
@@ -24,3 +34,8 @@ static toJson(value: string) {
    * Converts a valid JSON object to a string
-   * @param value
+   * @param value - A JSON object
+   * @returns - A JSON string
+   * @example
+   * const jsonObject = { name: 'John', age: 30, city: 'New York' };
+   * const jsonString = Stringify.toString(jsonObject);
+   * console.log(jsonString); // '{"name":"John","age":30,"city":"New York"}'
    */
@@ -36,4 +51,9 @@ static toString(value: string) {
   /**
-   * Encrypts string
-   * @param value
+   * Encrypts a string using the encryption key
+   * @param value - The string to encrypt
+   * @returns - The encrypted string
+   * @example
+   * const plaintext = 'my secret message';
+   * const encrypted = Stringify.toEncryptedString(plaintext);
+   * console.log(encrypted); // Encrypted string
    */
@@ -50,4 +70,9 @@ static toEncryptedString(value: any) {
   /**
-   * Decrypts encrypted string to plain text
-   * @param value
+   * Decrypts an encrypted string to plain text using the encryption key
+   * @param value - The encrypted string
+   * @returns - The decrypted string
+   * @example
+   * const encrypted = 'Encrypted string';
+   * const plaintext = Stringify.toDecryptedString(encrypted);
+   * console.log(plaintext); // 'my secret message'
    */
@@ -63,5 +88,11 @@ static toDecryptedString(value: string) {
 
+
   /**
-   * Decrypts string to JSON object be sure that the encrypted data was a json object
-   * @param value
+   * Decrypts an encrypted string to a JSON object using the encryption key
+   * @param value - The encrypted JSON string
+   * @returns - The decrypted JSON object
+   * @example
+   * const encrypted = 'Encrypted JSON string';
+   * const jsonObject = Stringify.toDecryptedJSON(encrypted);
+   * console.log(jsonObject); // Decrypted JSON object
    */
@@ -82,4 +113,9 @@ static toDecryptedJSON(value: string) {
   /**
-   * Converts str value to camel case. Eg. example_sentence: exampleSentence
-   * @param str
+   * Converts a string to camel case
+   * @param str - The string to convert
+   * @returns - The camel case string
+   * @example
+   * const sentence = 'example_sentence';
+   * const camelCase = Stringify.toCamelCase(sentence);
+   * console.log(camelCase); // 'exampleSentence'
    */
@@ -91,4 +127,9 @@ static toCamelCase(str: string): string {
   /**
-   * Converts str value to snake case. Eg. exampleSentence: example_sentence
-   * @param str
+   * Converts a string to snake case
+   * @param str - The string to convert
+   * @returns - The snake case string
+   * @example
+   * const sentence = 'exampleSentence';
+   * const snakeCase = Stringify.toSnakeCase(sentence);
+   * console.log(snakeCase); // 'example_sentence'
    */
@@ -102,5 +143,9 @@ static toSnakeCase(str: string): string {
   /**
-   * Converts str value to Kebab case. Eg. example_sentence: example-sentence
-   * @param str
-   * @returns {string}
+   * Converts a string to kebab case
+   * @param str - The string to convert
+   * @returns - The kebab case string
+   * @example
+   * const sentence = 'example_sentence';
+   * const kebabCase = Stringify.toKebabCase(sentence);
+   * console.log(kebabCase); // 'example-sentence'
    */
@@ -114,5 +159,9 @@ static toKebabCase(str: string): string {
   /**
-   * Converts str value to sentence case. Eg. example sentence: Example sentence
-   * @param str
-   * @returns {string}
+   * Converts a string to sentence case
+   * @param str - The string to convert
+   * @returns - The sentence case string
+   * @example
+   * const sentence = 'this is an example sentence.';
+   * const sentenceCase = Stringify.toSentenceCase(sentence);
+   * console.log(sentenceCase); // 'This is an example sentence.'
    */
@@ -124,7 +173,8 @@ static toSentenceCase(str: string): string {
   /**
-   * Converts str value to Title case.
+   * Converts a string value to Title Case.
    * @example
-   * example sentence returns Example Sentence
-   * @param str
-   * @returns {string}
+   * // Returns "Example Sentence"
+   * Stringify.toTitleCase("example sentence");
+   * @param {string} str - The string to convert to Title Case.
+   * @returns {string} The converted string.
    */
@@ -138,8 +188,8 @@ static toTitleCase(str: string): string {
   /**
-   * Converts str value to sentence case.
+   * Converts a string value to Uppercase.
    * @example
    * // Returns "EXAMPLE SENTENCE"
-   * Stringify.toUpperCase("example sentence")
-   * @param str
-   * @returns {string}
+   * Stringify.toUpperCase("example sentence");
+   * @param {string} str - The string to convert to Uppercase.
+   * @returns {string} The converted string.
    */
@@ -151,7 +201,8 @@ static toUpperCase(str: string): string {
   /**
-   * Converts str value to sentence case.
+   * Converts a string value to Lowercase.
    * @example
    * // Returns "example sentence"
-   * Stringify.toLowerCase("Example Sentence")
-   * @param str
+   * Stringify.toLowerCase("Example Sentence");
+   * @param {string} str - The string to convert to Lowercase.
+   * @returns {string} The converted string.
    */
@@ -167,2 +218,10 @@ static toLowerCase(str: string): string {
 
+  /**
+   * Encodes an object into a query string.
+   * @example
+   * // Returns "param1=value1&param2=value2"
+   * Stringify.encodeQueryString({ param1: "value1", param2: "value2" });
+   * @param {object} params - The object to encode into a query string.
+   * @returns {string} The encoded query string.
+   */
   static encodeQueryString(params: Record<string, any>): string {
@@ -178,2 +237,10 @@ const queryParams = new URLSearchParams();
 
+  /**
+   * Decodes a query string into an object.
+   * @example
+   * // Returns { param1: "value1", param2: "value2" }
+   * Stringify.decodeQueryString("param1=value1&param2=value2");
+   * @param {string} queryString - The query string to decode into an object.
+   * @returns {object} The decoded object.
+   */
   static decodeQueryString(queryString: string): Record<string, any> {
@@ -188,2 +255,10 @@ const queryParams = new URLSearchParams(queryString);
 
+  /**
+   * Parses a URL into an object.
+   * @example
+   * // Returns { protocol: "http:", hostname: "example.com", port: "", pathname: "/", search: "?param1=value1&param2=value2" }
+   * Stringify.parseUrl("http://example.com/?param1=value1&param2=value2");
+   * @param {string} url - The URL to parse into an object.
+   * @returns {object} The parsed object.
+   */
   static parseUrl(url: string): Record<string, any> {
@@ -208,2 +283,11 @@ const parsedUrl = new URL(url);
 
+  /**
+   * Formats a string template with the given values.
+   * @example
+   * // Returns "Hello, John!"
+   * Stringify.formatString("Hello, ${name}!", { name: "John" });
+   * @param {string} template The string template to format.
+   * @param {Record<string, any>} values The values to replace in the template.
+   * @returns {string} The formatted string.
+   */
   static formatString(template: string, values: Record<string, any>): string {
@@ -215,2 +299,12 @@ return template.replace(/\${(.*?)}/g, (_, key) => {
 
+  /**
+   * Pads the left side of a string with a padding character until it reaches the given length.
+   * @example
+   * // Returns "  abc"
+   * Stringify.padLeft("abc", 4);
+   * @param {string} str The string to pad.
+   * @param {number} length The desired length of the string after padding.
+   * @param {string} [paddingChar=" "] The character to use for padding. Defaults to " ".
+   * @returns {string} The padded string.
+   */
   static padLeft(str: string, length: number, paddingChar: string = " "): string {
@@ -221,2 +315,12 @@ const padding = paddingChar.repeat(length);
 
+  /**
+   * Pads the right side of a string with a padding character until it reaches the given length.
+   * @example
+   * // Returns "abc  "
+   * Stringify.padRight("abc", 4);
+   * @param {string} str The string to pad.
+   * @param {number} length The desired length of the string after padding.
+   * @param {string} [paddingChar=" "] The character to use for padding. Defaults to " ".
+   * @returns {string} The padded string.
+   */
   static padRight(str: string, length: number, paddingChar: string = " "): string {
@@ -227,2 +331,12 @@ const padding = paddingChar.repeat(length);
 
+  /**
+   * Truncates a string to the given maximum length, adding a suffix if necessary.
+   * @example
+   * // Returns "Hello, ..."
+   * Stringify.truncate("Hello, world!", 8);
+   * @param {string} str The string to truncate.
+   * @param {number} maxLength The maximum length of the truncated string.
+   * @param {string} [suffix="..."] The suffix to add if the string is truncated. Defaults to "...".
+   * @returns {string} The truncated string.
+   */
   static truncate(str: string, maxLength: number, suffix: string = "..."): string {
@@ -235,4 +349,2 @@ if (str.length > maxLength) {
   }
-
-
 }

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

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

37323

increased by63.2%

Dependency count

1

decreased by-50%

Lines of code

605

increased by22.72%

Number of lines in readme file

322

increased by16000%

Dependency changes

• - [e-mail]/stringify@^1.0.0