lifecycleion 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,125 @@
+# Lifecycleion v0.0.1
+
+[![npm version](https://badge.fury.io/js/lifecycleion.svg)](https://badge.fury.io/js/lifecycleion)
+
+A collection of foundational TypeScript utilities for managing application lifecycle, logging, retries, events, and common programming patterns.
+
+<!-- toc -->
+
+- [Why Lifecycleion?](#why-lifecycleion)
+  - [Key Features](#key-features)
+- [Installation](#installation)
+- [Quick Example](#quick-example)
+- [Available Libraries](#available-libraries)
+- [Change Log](#change-log)
+- [Contributing](#contributing)
+- [License](#license)
+
+<!-- tocstop -->
+
+## Why Lifecycleion?
+
+Lifecycleion provides battle-tested, production-ready utilities that handle the complex orchestration of modern applications. Whether you need graceful shutdowns, robust retry logic, flexible logging, or just reliable helper functions, Lifecycleion has you covered.
+
+### Key Features
+
+- 🚀 **Lifecycle Management** - Orchestrate startup, shutdown, and runtime control of application components with dependency resolution
+- 🪵 **Flexible Logger** - Sink-based logger with log levels, redaction, and service scoping
+- 🔄 **Retry Utilities** - Fixed and exponential backoff strategies with cancellation support
+- 📡 **Event Systems** - Event emitters for multiple event types and single-event observers with type safety
+- 🛡️ **Error Handling** - Serialize errors for IPC/RPC, format them as readable tables, and handle callbacks safely
+- 🔧 **Common Utilities** - ID generation (UUID, ULID, ObjectID), string manipulation, deep cloning, and more
+- 📦 **Tree-shakeable** - Import only what you need via subpath exports
+- 💪 **TypeScript-first** - Full type safety with comprehensive TypeScript definitions
+
+## Installation
+
+```bash
+npm install lifecycleion
+# or
+yarn add lifecycleion
+# or
+bun add lifecycleion
+```
+
+## Quick Example
+
+```typescript
+import {
+  LifecycleManager,
+  BaseComponent,
+} from 'lifecycleion/lifecycle-manager';
+import { createLogger } from 'lifecycleion/logger';
+import { RetryRunner } from 'lifecycleion/retry-utils';
+
+// Create a logger
+const logger = createLogger({ service: 'my-app' });
+
+// Set up retry logic
+const runner = new RetryRunner({ maxAttempts: 3, baseDelayMs: 1000 });
+await runner.run(async () => {
+  // Your operation here
+});
+
+// Manage component lifecycle
+class MyComponent extends BaseComponent {
+  async start() {
+    logger.info('Starting component');
+  }
+
+  async stop() {
+    logger.info('Stopping component');
+  }
+}
+
+const manager = new LifecycleManager();
+manager.registerComponent(new MyComponent('my-component'));
+await manager.startAllComponents();
+```
+
+## Available Libraries
+
+Each library has comprehensive documentation in the [docs](./docs) folder. Click on any library name in the table below to view detailed usage examples, API references, and best practices.
+
+| Library                                                            | Import Path                               | Description                                                                                                                              |
+| ------------------------------------------------------------------ | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| [arrays](./docs/arrays.md)                                         | `lifecycleion/arrays`                     | Array utility functions for filtering, comparison, deduplication, and string manipulation                                                |
+| [ascii-tables](./docs/ascii-tables.md)                             | `lifecycleion/ascii-tables`               | Key-value and multi-column ASCII tables with word wrapping, nesting, and emoji support                                                   |
+| [clamp](./docs/clamp.md)                                           | `lifecycleion/clamp`                      | Number clamping utilities with safe handling for non-finite values and nullish inputs                                                    |
+| [constants](./docs/constants.md)                                   | `lifecycleion/constants`                  | Common string constants including whitespace helpers and Python-style character sets                                                     |
+| [curly-brackets](./docs/curly-brackets.md)                         | `lifecycleion/curly-brackets`             | String templating with `{{placeholders}}`, fallbacks, escaping, and compiled templates                                                   |
+| [deep-clone](./docs/deep-clone.md)                                 | `lifecycleion/deep-clone`                 | Deep clone utility with circular reference detection for objects, arrays, Maps, Sets, and more                                           |
+| [error-to-string](./docs/error-to-string.md)                       | `lifecycleion/error-to-string`            | Format errors into readable ASCII tables with support for nested info and sensitive field masking                                        |
+| [event-emitter](./docs/event-emitter.md)                           | `lifecycleion/event-emitter`              | Lightweight event emitter with protected and public variants, type safety, and memory management                                         |
+| [id-helpers](./docs/id-helpers.md)                                 | `lifecycleion/id-helpers`                 | Unified ID generation and validation for ObjectID, UUID v4, UUID v7, and ULID                                                            |
+| [is-boolean](./docs/is-boolean.md)                                 | `lifecycleion/is-boolean`                 | Type guard to check if a value is a boolean                                                                                              |
+| [is-function](./docs/is-function.md)                               | `lifecycleion/is-function`                | Check whether a value is a function                                                                                                      |
+| [is-number](./docs/is-number.md)                                   | `lifecycleion/is-number`                  | Type guards to check whether a value is a valid number, with and without finite enforcement                                              |
+| [is-plain-object](./docs/is-plain-object.md)                       | `lifecycleion/is-plain-object`            | Type guard to check if a value is a plain object (not null, not an array)                                                                |
+| [is-promise](./docs/is-promise.md)                                 | `lifecycleion/is-promise`                 | Thenable/promise detection following the Promises/A+ specification                                                                       |
+| [json-helpers](./docs/json-helpers.md)                             | `lifecycleion/json-helpers`               | JSON formatting utilities                                                                                                                |
+| [lifecycle-manager](./docs/lifecycle-manager.md)                   | `lifecycleion/lifecycle-manager`          | Lifecycle orchestration for managing startup, shutdown, and runtime control of application components                                    |
+| [logger](./docs/logger.md)                                         | `lifecycleion/logger`                     | Flexible sink-based logger with log levels, redaction, template strings, and service scoping                                             |
+| [padding-utils](./docs/padding-utils.md)                           | `lifecycleion/padding-utils`              | String padding utilities for left, right, and center alignment with a configurable pad character                                         |
+| [process-signal-manager](./docs/process-signal-manager.md)         | `lifecycleion/process-signal-manager`     | Unified handler for process signals (SIGINT, SIGTERM, SIGHUP, etc.) and keyboard shortcuts with graceful shutdown and hot-reload support |
+| [promise-protected-resolver](./docs/promise-protected-resolver.md) | `lifecycleion/promise-protected-resolver` | Promise wrapper with `resolveOnce` and `rejectOnce` that guarantee a promise is only settled once                                        |
+| [retry-utils](./docs/retry-utils.md)                               | `lifecycleion/retry-utils`                | Retry logic with fixed and exponential backoff via `RetryPolicy` (low-level) and `RetryRunner` (high-level with events and cancellation) |
+| [safe-handle-callback](./docs/safe-handle-callback.md)             | `lifecycleion/safe-handle-callback`       | Safely execute sync or async callbacks with automatic error reporting via the standard `reportError` event API                           |
+| [serialize-error](./docs/serialize-error.md)                       | `lifecycleion/serialize-error`            | Convert any `Error` into a plain JSON-serializable object and back again for IPC, RPCs, and database storage                             |
+| [single-event-observer](./docs/single-event-observer.md)           | `lifecycleion/single-event-observer`      | Lightweight type-safe observer pattern for a single event type, with public and protected notify variants                                |
+| [sleep](./docs/sleep.md)                                           | `lifecycleion/sleep`                      | Pause async execution for a given number of milliseconds                                                                                 |
+| [strings](./docs/strings.md)                                       | `lifecycleion/strings`                    | String type guard, case conversion (PascalCase, camelCase, CONSTANT_CASE), grapheme splitting, character filtering, and chopping helpers |
+| [tmp-dir](./docs/tmp-dir.md)                                       | `lifecycleion/tmp-dir`                    | Create and automatically clean up uniquely-named temporary directories with configurable prefix, postfix, and unsafe cleanup support     |
+| [unix-time-helpers](./docs/unix-time-helpers.md)                   | `lifecycleion/unix-time-helpers`          | Unix timestamp utilities for seconds, milliseconds, high-resolution timing, and unit conversion                                          |
+
+## Change Log
+
+See [changelog.md](./changelog.md) for version history and release notes.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests on [GitHub](https://github.com/keverw/lifecycleion).
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) file for details.

package/dist/index.cjs

@@ -0,0 +1,7 @@
+"use strict";
+
+// src/index.ts
+throw new Error(
+  'Lifecycleion does not support default imports. Import from specific subpaths like "lifecycleion/arrays", "lifecycleion/logger", etc. See README for all available imports: https://github.com/keverw/lifecycleion#readme'
+);
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Lifecycleion is a collection of utility libraries.\n *\n * Import from specific subpaths instead of the package root:\n *\n * @example\n * ```typescript\n * // ✅ Correct - Import from subpaths\n * import { chunk } from \"lifecycleion/arrays\"\n * import { Logger } from \"lifecycleion/logger\"\n * import { sleep } from \"lifecycleion/sleep\"\n *\n * // ❌ Wrong - Don't import from package root\n * import { something } from \"lifecycleion\"\n * ```\n *\n * See the README for a complete list of available imports:\n * https://github.com/keverw/lifecycleion#readme\n */\n\nthrow new Error(\n  'Lifecycleion does not support default imports. ' +\n    'Import from specific subpaths like \"lifecycleion/arrays\", \"lifecycleion/logger\", etc. ' +\n    'See README for all available imports: https://github.com/keverw/lifecycleion#readme',\n);\n"],"mappings":";;;AAoBA,MAAM,IAAI;AAAA,EACR;AAGF;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,5 @@
+// src/index.ts
+throw new Error(
+  'Lifecycleion does not support default imports. Import from specific subpaths like "lifecycleion/arrays", "lifecycleion/logger", etc. See README for all available imports: https://github.com/keverw/lifecycleion#readme'
+);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Lifecycleion is a collection of utility libraries.\n *\n * Import from specific subpaths instead of the package root:\n *\n * @example\n * ```typescript\n * // ✅ Correct - Import from subpaths\n * import { chunk } from \"lifecycleion/arrays\"\n * import { Logger } from \"lifecycleion/logger\"\n * import { sleep } from \"lifecycleion/sleep\"\n *\n * // ❌ Wrong - Don't import from package root\n * import { something } from \"lifecycleion\"\n * ```\n *\n * See the README for a complete list of available imports:\n * https://github.com/keverw/lifecycleion#readme\n */\n\nthrow new Error(\n  'Lifecycleion does not support default imports. ' +\n    'Import from specific subpaths like \"lifecycleion/arrays\", \"lifecycleion/logger\", etc. ' +\n    'See README for all available imports: https://github.com/keverw/lifecycleion#readme',\n);\n"],"mappings":";AAoBA,MAAM,IAAI;AAAA,EACR;AAGF;","names":[]}

package/dist/lib/arrays.cjs

@@ -0,0 +1,95 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/arrays.ts
+var arrays_exports = {};
+__export(arrays_exports, {
+  areArraysEqual: () => areArraysEqual,
+  isArray: () => isArray,
+  isEveryArrayItemAnString: () => isEveryArrayItemAnString,
+  prependStringToArrayItems: () => prependStringToArrayItems,
+  pushWithoutDuplicates: () => pushWithoutDuplicates,
+  removeEmptyStringsFromArray: () => removeEmptyStringsFromArray
+});
+module.exports = __toCommonJS(arrays_exports);
+
+// src/lib/strings.ts
+function isString(value) {
+  return typeof value === "string";
+}
+
+// src/lib/arrays.ts
+function isArray(value) {
+  return Array.isArray(value);
+}
+function removeEmptyStringsFromArray(array) {
+  const newArray = [];
+  for (let item of array) {
+    item = item.trim();
+    if (item.length > 0) {
+      newArray.push(item);
+    }
+  }
+  return newArray;
+}
+function prependStringToArrayItems(array, value) {
+  const newArray = [];
+  for (const item of array) {
+    newArray.push(value + item);
+  }
+  return newArray;
+}
+function isEveryArrayItemAnString(value) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (!isString(item)) {
+        return false;
+      }
+    }
+    return true;
+  } else {
+    return false;
+  }
+}
+function areArraysEqual(arr1, arr2) {
+  if (arr1.length !== arr2.length) {
+    return false;
+  }
+  for (const [i, element] of arr1.entries()) {
+    if (element !== arr2[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+function pushWithoutDuplicates(array, value) {
+  if (!array.includes(value)) {
+    array.push(value);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  areArraysEqual,
+  isArray,
+  isEveryArrayItemAnString,
+  prependStringToArrayItems,
+  pushWithoutDuplicates,
+  removeEmptyStringsFromArray
+});
+//# sourceMappingURL=arrays.cjs.map

package/dist/lib/arrays.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/arrays.ts","../../src/lib/strings.ts"],"sourcesContent":["import { isString } from './strings';\n\nexport function isArray(value: unknown): value is unknown[] {\n  return Array.isArray(value);\n}\n\nexport function removeEmptyStringsFromArray(array: string[]): string[] {\n  const newArray: string[] = [];\n\n  for (let item of array) {\n    item = item.trim();\n\n    if (item.length > 0) {\n      newArray.push(item);\n    }\n  }\n\n  return newArray;\n}\n\n/**\n * Will take an array and return a new array with a value prepended to each item\n *\n * @param array\n * @param value\n * @returns\n */\n\nexport function prependStringToArrayItems(\n  array: string[],\n  value: string,\n): string[] {\n  const newArray: string[] = [];\n\n  for (const item of array) {\n    newArray.push(value + item);\n  }\n\n  return newArray;\n}\n\nexport function isEveryArrayItemAnString(value: unknown): boolean {\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      if (!isString(item)) {\n        return false;\n      }\n    }\n\n    return true;\n  } else {\n    return false;\n  }\n}\n\nexport function areArraysEqual<T>(arr1: T[], arr2: T[]): boolean {\n  // Check if the arrays are the same length\n  if (arr1.length !== arr2.length) {\n    return false;\n  }\n\n  // Check each element in the arrays\n  for (const [i, element] of arr1.entries()) {\n    if (element !== arr2[i]) {\n      return false;\n    }\n  }\n\n  // If all elements are equal\n  return true;\n}\n\nexport function pushWithoutDuplicates(array: unknown[], value: unknown): void {\n  if (!array.includes(value)) {\n    array.push(value);\n  }\n}\n","import { removeEmptyStringsFromArray } from './arrays';\n\nexport function isString(value: unknown): value is string {\n  return typeof value === 'string';\n}\n\n/**\n * Converts a string or an array of strings to Pascal Case.\n *\n * This function takes an input string or an array of strings, each potentially containing hyphens,\n * and converts them to Pascal Case. It removes any characters that are not letters or numbers,\n * capitalizes the first letter of each substring, and ensures the rest of the substring\n * is in lowercase. Finally, it concatenates all these substrings to produce a Pascal Case\n * output.\n *\n * @param {string | string[]} input - The input string or array of strings to be converted to Pascal Case.\n * @returns {string} The converted string in Pascal Case.\n *\n * Examples:\n * toPascalCase(\"hello-world-123!$\") will return \"HelloWorld123\"\n * toPascalCase([\"hello\", \"world-123!$\"]) will return \"HelloWorld123\"\n */\n\nexport function toPascalCase(input: string | string[]): string {\n  // Ensure input is an array\n  const inputArray = Array.isArray(input) ? input : [input];\n\n  // Process each string in the array\n  const parts: string[] = [];\n\n  for (const item of inputArray) {\n    // Clean the string, split by hyphen, and remove empty strings\n    const cleanedItem = item.replace(/[^a-zA-Z0-9-]/g, '');\n    parts.push(...removeEmptyStringsFromArray(cleanedItem.split('-')));\n  }\n\n  // Process and rejoin the input strings\n  return parts\n    .map(\n      (subString) =>\n        subString.charAt(0).toUpperCase() + subString.slice(1).toLowerCase(),\n    )\n    .join('');\n}\n\n/**\n * Converts a string or an array of strings to Camel Case.\n *\n * This function takes an input string or an array of strings, each potentially containing hyphens,\n * and converts them to Camel Case. It removes any characters that are not letters or numbers,\n * capitalizes the first letter of each substring after the first one, and ensures the rest of the substring\n * is in lowercase. For the first substring, it ensures the entire substring is in lowercase.\n * Finally, it concatenates all these substrings to produce a Camel Case output.\n *\n * @param {string | string[]} input - The input string or array of strings to be converted to Camel Case.\n * @returns {string} The converted string in Camel Case.\n *\n * Examples:\n * toCamelCase(\"hello-world-123!$\") will return \"helloWorld123\"\n * toCamelCase([\"hello\", \"world-123!$\"]) will return \"helloWorld123\"\n */\n\nexport function toCamelCase(input: string | string[]): string {\n  // Ensure input is an array\n  const inputArray = Array.isArray(input) ? input : [input];\n\n  // Process each string in the array\n  const parts: string[] = [];\n\n  for (const item of inputArray) {\n    // Clean the string, split by hyphen, and remove empty strings\n    const cleanedItem = item.replace(/[^a-zA-Z0-9-]/g, '');\n    parts.push(...removeEmptyStringsFromArray(cleanedItem.split('-')));\n  }\n\n  // Process and rejoin the input strings\n  return parts\n    .map((subString, index) =>\n      index === 0\n        ? subString.toLowerCase()\n        : subString.charAt(0).toUpperCase() + subString.slice(1).toLowerCase(),\n    )\n    .join('');\n}\n\n/**\n * This method converts a string or an array of strings to camel case,\n * but if starting with a leading hyphen, it will convert to Pascal case.\n */\n\nexport function toCamelCaseWithPascalOverride(\n  input: string | string[],\n): string {\n  if (isString(input) && input.startsWith('-')) {\n    return toPascalCase(input);\n  } else if (\n    Array.isArray(input) &&\n    input.length > 0 &&\n    input[0].startsWith('-')\n  ) {\n    return toPascalCase(input);\n  } else {\n    return toCamelCase(input);\n  }\n}\n\n/**\n * Converts a string or an array of strings to constant case.\n *\n * The function takes a string or an array of strings, where each string can be separated by a '-',\n * and converts them into a constant case format (all uppercase with underscores between words).\n * It first cleans the input by removing non-alphanumeric characters (except for hyphens), splits the\n * string into parts on hyphens, and then joins these parts with underscores, converting the entire\n * result to uppercase.\n *\n * @param {string | string[]} input - The input string or array of strings to be converted.\n * @returns {string} The converted string in constant case.\n *\n * Example:\n * toConstantCase(\"hello-world\") will return \"HELLO_WORLD\"\n * toConstantCase([\"hello\", \"world\"]) will return \"HELLO_WORLD\"\n */\n\nexport function toConstantCase(input: string | string[]): string {\n  // Ensure input is an array\n  const inputArray = Array.isArray(input) ? input : [input];\n\n  // Process each string in the array\n  let parts: string[] = [];\n\n  for (const item of inputArray) {\n    // Clean the string and split by hyphen\n    const cleanedItem = item.replace(/[^a-zA-Z0-9-]/g, '');\n    parts.push(...cleanedItem.split('-'));\n  }\n\n  // Remove empty strings from the array\n  parts = removeEmptyStringsFromArray(parts);\n\n  // Join parts with underscore and convert to uppercase\n  return parts.join('_').toUpperCase();\n}\n\nexport function splitGraphemes(text: string): string[] {\n  const graphemes: string[] = [];\n  let grapheme = '';\n  let zwjSequence = '';\n\n  for (let i = 0; i < text.length; i++) {\n    const char = text[i];\n    const nextChar = text[i + 1] || '';\n    const code = char.charCodeAt(0);\n\n    // Handling combining marks and zero width joiner\n    if (\n      (code >= 0x0300 && code <= 0x036f) || // Combining Diacritical Marks\n      (code >= 0x1ab0 && code <= 0x1aff) || // Combining Diacritical Marks Extended\n      (code >= 0x1dc0 && code <= 0x1dff) || // Combining Diacritical Marks Supplement\n      (code >= 0xfe20 && code <= 0xfe2f) || // Combining Half Marks\n      (code >= 0x0e31 && code <= 0x0e3a) || // Thai combining marks\n      (code >= 0x0e47 && code <= 0x0e4e)\n    ) {\n      // Thai combining marks\n      grapheme += char;\n    } else if (char === '\\u200d') {\n      // Zero Width Joiner (ZWJ)\n      zwjSequence += grapheme + char;\n      grapheme = '';\n    } else {\n      if (grapheme) {\n        if (zwjSequence) {\n          graphemes.push(zwjSequence + grapheme);\n          zwjSequence = '';\n        } else {\n          graphemes.push(grapheme);\n        }\n      }\n      grapheme = char;\n\n      // Handle surrogate pairs (needed for certain characters including emojis)\n      if (\n        char >= '\\ud800' &&\n        char <= '\\udbff' &&\n        nextChar >= '\\udc00' &&\n        nextChar <= '\\udfff'\n      ) {\n        grapheme += nextChar;\n        i++;\n      }\n    }\n  }\n\n  if (grapheme) {\n    if (zwjSequence) {\n      graphemes.push(zwjSequence + grapheme);\n    } else {\n      graphemes.push(grapheme);\n    }\n  }\n\n  return graphemes;\n}\n\nexport function skipTrailingNewLines(str: string): string {\n  return str.replace(/\\n+$/, '');\n}\n\n/**\n * Filters a string to include only specified characters, optionally replacing disallowed characters.\n *\n * @param str - The input string to be filtered.\n * @param list - An array of allowed characters.\n * @param caseInsensitive - Optional. If true, the filtering is case-insensitive. Default is false.\n * @param replacementChar - Optional. Character to replace disallowed characters. If empty, disallowed characters are removed. Default is ''.\n * @returns A new string containing only the allowed characters from the input string, with disallowed characters optionally replaced.\n *\n * @example\n * // Case-sensitive usage, removing disallowed characters\n * characterAllowedOnly(\"Hello123!\", [\"H\", \"e\", \"l\", \"o\"]);\n * // Returns: \"Hello\"\n *\n * @example\n * // Case-insensitive usage, removing disallowed characters\n * characterAllowedOnly(\"Hello123!\", [\"h\", \"E\", \"L\", \"O\"], true);\n * // Returns: \"Hello\"\n *\n * @example\n * // Using replacement character\n * characterAllowedOnly(\"Hello123!\", [\"H\", \"e\", \"l\", \"o\"], false, \"-\");\n * // Returns: \"Hello---\"\n */\n\nexport function characterAllowedOnly(\n  str: string,\n  list: string[],\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  caseInsensitive = false,\n  replacementChar = '',\n): string {\n  let newStr = '';\n\n  // Convert the allowed list to lowercase if case-insensitive\n  if (caseInsensitive) {\n    list = Array.from(new Set(list.map((item) => item.toLowerCase())));\n  }\n\n  // Convert the entire input string to lowercase if case-insensitive\n  const processedStr = caseInsensitive ? str.toLowerCase() : str;\n\n  for (const c of processedStr) {\n    if (list.includes(c)) {\n      newStr += c;\n    } else if (replacementChar !== '') {\n      newStr += replacementChar;\n    }\n  }\n\n  return newStr;\n}\n\n// functions to chop characters from a string.\n\n/**\n * Will remove the matching first character from a string\n * @param str\n * @param char\n * @returns\n */\n\nexport function chopBeginningCharacter(str: string, char: string): string {\n  if (str.startsWith(char)) {\n    return str.slice(1);\n  } else {\n    return str;\n  }\n}\n\n/**\n * Will remove the matching last character from the string\n * @param str\n * @param char\n * @returns\n */\nexport function chopEndingCharacter(str: string, char: string): string {\n  if (str.endsWith(char)) {\n    return str.slice(0, -1);\n  } else {\n    return str;\n  }\n}\n\n/**\n * Will remove the matching character, from the beginning and/or end of the string if matching\n * @param str\n * @param char\n * @returns\n */\n\nexport function chopBothBeginningAndEndingCharacters(\n  str: string,\n  char: string,\n): string {\n  return chopBeginningCharacter(chopEndingCharacter(str, char), char);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACEO,SAAS,SAAS,OAAiC;AACxD,SAAO,OAAO,UAAU;AAC1B;;;ADFO,SAAS,QAAQ,OAAoC;AAC1D,SAAO,MAAM,QAAQ,KAAK;AAC5B;AAEO,SAAS,4BAA4B,OAA2B;AACrE,QAAM,WAAqB,CAAC;AAE5B,WAAS,QAAQ,OAAO;AACtB,WAAO,KAAK,KAAK;AAEjB,QAAI,KAAK,SAAS,GAAG;AACnB,eAAS,KAAK,IAAI;AAAA,IACpB;AAAA,EACF;AAEA,SAAO;AACT;AAUO,SAAS,0BACd,OACA,OACU;AACV,QAAM,WAAqB,CAAC;AAE5B,aAAW,QAAQ,OAAO;AACxB,aAAS,KAAK,QAAQ,IAAI;AAAA,EAC5B;AAEA,SAAO;AACT;AAEO,SAAS,yBAAyB,OAAyB;AAChE,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,eAAW,QAAQ,OAAO;AACxB,UAAI,CAAC,SAAS,IAAI,GAAG;AACnB,eAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO;AAAA,EACT,OAAO;AACL,WAAO;AAAA,EACT;AACF;AAEO,SAAS,eAAkB,MAAW,MAAoB;AAE/D,MAAI,KAAK,WAAW,KAAK,QAAQ;AAC/B,WAAO;AAAA,EACT;AAGA,aAAW,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,GAAG;AACzC,QAAI,YAAY,KAAK,CAAC,GAAG;AACvB,aAAO;AAAA,IACT;AAAA,EACF;AAGA,SAAO;AACT;AAEO,SAAS,sBAAsB,OAAkB,OAAsB;AAC5E,MAAI,CAAC,MAAM,SAAS,KAAK,GAAG;AAC1B,UAAM,KAAK,KAAK;AAAA,EAClB;AACF;","names":[]}

package/dist/lib/arrays.d.cts

@@ -0,0 +1,15 @@
+declare function isArray(value: unknown): value is unknown[];
+declare function removeEmptyStringsFromArray(array: string[]): string[];
+/**
+ * Will take an array and return a new array with a value prepended to each item
+ *
+ * @param array
+ * @param value
+ * @returns
+ */
+declare function prependStringToArrayItems(array: string[], value: string): string[];
+declare function isEveryArrayItemAnString(value: unknown): boolean;
+declare function areArraysEqual<T>(arr1: T[], arr2: T[]): boolean;
+declare function pushWithoutDuplicates(array: unknown[], value: unknown): void;
+
+export { areArraysEqual, isArray, isEveryArrayItemAnString, prependStringToArrayItems, pushWithoutDuplicates, removeEmptyStringsFromArray };

package/dist/lib/arrays.d.ts

@@ -0,0 +1,15 @@
+declare function isArray(value: unknown): value is unknown[];
+declare function removeEmptyStringsFromArray(array: string[]): string[];
+/**
+ * Will take an array and return a new array with a value prepended to each item
+ *
+ * @param array
+ * @param value
+ * @returns
+ */
+declare function prependStringToArrayItems(array: string[], value: string): string[];
+declare function isEveryArrayItemAnString(value: unknown): boolean;
+declare function areArraysEqual<T>(arr1: T[], arr2: T[]): boolean;
+declare function pushWithoutDuplicates(array: unknown[], value: unknown): void;
+
+export { areArraysEqual, isArray, isEveryArrayItemAnString, prependStringToArrayItems, pushWithoutDuplicates, removeEmptyStringsFromArray };

package/dist/lib/arrays.js

@@ -0,0 +1,63 @@
+// src/lib/strings.ts
+function isString(value) {
+  return typeof value === "string";
+}
+
+// src/lib/arrays.ts
+function isArray(value) {
+  return Array.isArray(value);
+}
+function removeEmptyStringsFromArray(array) {
+  const newArray = [];
+  for (let item of array) {
+    item = item.trim();
+    if (item.length > 0) {
+      newArray.push(item);
+    }
+  }
+  return newArray;
+}
+function prependStringToArrayItems(array, value) {
+  const newArray = [];
+  for (const item of array) {
+    newArray.push(value + item);
+  }
+  return newArray;
+}
+function isEveryArrayItemAnString(value) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (!isString(item)) {
+        return false;
+      }
+    }
+    return true;
+  } else {
+    return false;
+  }
+}
+function areArraysEqual(arr1, arr2) {
+  if (arr1.length !== arr2.length) {
+    return false;
+  }
+  for (const [i, element] of arr1.entries()) {
+    if (element !== arr2[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+function pushWithoutDuplicates(array, value) {
+  if (!array.includes(value)) {
+    array.push(value);
+  }
+}
+export {
+  areArraysEqual,
+  isArray,
+  isEveryArrayItemAnString,
+  prependStringToArrayItems,
+  pushWithoutDuplicates,
+  removeEmptyStringsFromArray
+};
+//# sourceMappingURL=arrays.js.map

package/dist/lib/arrays.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/strings.ts","../../src/lib/arrays.ts"],"sourcesContent":["import { removeEmptyStringsFromArray } from './arrays';\n\nexport function isString(value: unknown): value is string {\n  return typeof value === 'string';\n}\n\n/**\n * Converts a string or an array of strings to Pascal Case.\n *\n * This function takes an input string or an array of strings, each potentially containing hyphens,\n * and converts them to Pascal Case. It removes any characters that are not letters or numbers,\n * capitalizes the first letter of each substring, and ensures the rest of the substring\n * is in lowercase. Finally, it concatenates all these substrings to produce a Pascal Case\n * output.\n *\n * @param {string | string[]} input - The input string or array of strings to be converted to Pascal Case.\n * @returns {string} The converted string in Pascal Case.\n *\n * Examples:\n * toPascalCase(\"hello-world-123!$\") will return \"HelloWorld123\"\n * toPascalCase([\"hello\", \"world-123!$\"]) will return \"HelloWorld123\"\n */\n\nexport function toPascalCase(input: string | string[]): string {\n  // Ensure input is an array\n  const inputArray = Array.isArray(input) ? input : [input];\n\n  // Process each string in the array\n  const parts: string[] = [];\n\n  for (const item of inputArray) {\n    // Clean the string, split by hyphen, and remove empty strings\n    const cleanedItem = item.replace(/[^a-zA-Z0-9-]/g, '');\n    parts.push(...removeEmptyStringsFromArray(cleanedItem.split('-')));\n  }\n\n  // Process and rejoin the input strings\n  return parts\n    .map(\n      (subString) =>\n        subString.charAt(0).toUpperCase() + subString.slice(1).toLowerCase(),\n    )\n    .join('');\n}\n\n/**\n * Converts a string or an array of strings to Camel Case.\n *\n * This function takes an input string or an array of strings, each potentially containing hyphens,\n * and converts them to Camel Case. It removes any characters that are not letters or numbers,\n * capitalizes the first letter of each substring after the first one, and ensures the rest of the substring\n * is in lowercase. For the first substring, it ensures the entire substring is in lowercase.\n * Finally, it concatenates all these substrings to produce a Camel Case output.\n *\n * @param {string | string[]} input - The input string or array of strings to be converted to Camel Case.\n * @returns {string} The converted string in Camel Case.\n *\n * Examples:\n * toCamelCase(\"hello-world-123!$\") will return \"helloWorld123\"\n * toCamelCase([\"hello\", \"world-123!$\"]) will return \"helloWorld123\"\n */\n\nexport function toCamelCase(input: string | string[]): string {\n  // Ensure input is an array\n  const inputArray = Array.isArray(input) ? input : [input];\n\n  // Process each string in the array\n  const parts: string[] = [];\n\n  for (const item of inputArray) {\n    // Clean the string, split by hyphen, and remove empty strings\n    const cleanedItem = item.replace(/[^a-zA-Z0-9-]/g, '');\n    parts.push(...removeEmptyStringsFromArray(cleanedItem.split('-')));\n  }\n\n  // Process and rejoin the input strings\n  return parts\n    .map((subString, index) =>\n      index === 0\n        ? subString.toLowerCase()\n        : subString.charAt(0).toUpperCase() + subString.slice(1).toLowerCase(),\n    )\n    .join('');\n}\n\n/**\n * This method converts a string or an array of strings to camel case,\n * but if starting with a leading hyphen, it will convert to Pascal case.\n */\n\nexport function toCamelCaseWithPascalOverride(\n  input: string | string[],\n): string {\n  if (isString(input) && input.startsWith('-')) {\n    return toPascalCase(input);\n  } else if (\n    Array.isArray(input) &&\n    input.length > 0 &&\n    input[0].startsWith('-')\n  ) {\n    return toPascalCase(input);\n  } else {\n    return toCamelCase(input);\n  }\n}\n\n/**\n * Converts a string or an array of strings to constant case.\n *\n * The function takes a string or an array of strings, where each string can be separated by a '-',\n * and converts them into a constant case format (all uppercase with underscores between words).\n * It first cleans the input by removing non-alphanumeric characters (except for hyphens), splits the\n * string into parts on hyphens, and then joins these parts with underscores, converting the entire\n * result to uppercase.\n *\n * @param {string | string[]} input - The input string or array of strings to be converted.\n * @returns {string} The converted string in constant case.\n *\n * Example:\n * toConstantCase(\"hello-world\") will return \"HELLO_WORLD\"\n * toConstantCase([\"hello\", \"world\"]) will return \"HELLO_WORLD\"\n */\n\nexport function toConstantCase(input: string | string[]): string {\n  // Ensure input is an array\n  const inputArray = Array.isArray(input) ? input : [input];\n\n  // Process each string in the array\n  let parts: string[] = [];\n\n  for (const item of inputArray) {\n    // Clean the string and split by hyphen\n    const cleanedItem = item.replace(/[^a-zA-Z0-9-]/g, '');\n    parts.push(...cleanedItem.split('-'));\n  }\n\n  // Remove empty strings from the array\n  parts = removeEmptyStringsFromArray(parts);\n\n  // Join parts with underscore and convert to uppercase\n  return parts.join('_').toUpperCase();\n}\n\nexport function splitGraphemes(text: string): string[] {\n  const graphemes: string[] = [];\n  let grapheme = '';\n  let zwjSequence = '';\n\n  for (let i = 0; i < text.length; i++) {\n    const char = text[i];\n    const nextChar = text[i + 1] || '';\n    const code = char.charCodeAt(0);\n\n    // Handling combining marks and zero width joiner\n    if (\n      (code >= 0x0300 && code <= 0x036f) || // Combining Diacritical Marks\n      (code >= 0x1ab0 && code <= 0x1aff) || // Combining Diacritical Marks Extended\n      (code >= 0x1dc0 && code <= 0x1dff) || // Combining Diacritical Marks Supplement\n      (code >= 0xfe20 && code <= 0xfe2f) || // Combining Half Marks\n      (code >= 0x0e31 && code <= 0x0e3a) || // Thai combining marks\n      (code >= 0x0e47 && code <= 0x0e4e)\n    ) {\n      // Thai combining marks\n      grapheme += char;\n    } else if (char === '\\u200d') {\n      // Zero Width Joiner (ZWJ)\n      zwjSequence += grapheme + char;\n      grapheme = '';\n    } else {\n      if (grapheme) {\n        if (zwjSequence) {\n          graphemes.push(zwjSequence + grapheme);\n          zwjSequence = '';\n        } else {\n          graphemes.push(grapheme);\n        }\n      }\n      grapheme = char;\n\n      // Handle surrogate pairs (needed for certain characters including emojis)\n      if (\n        char >= '\\ud800' &&\n        char <= '\\udbff' &&\n        nextChar >= '\\udc00' &&\n        nextChar <= '\\udfff'\n      ) {\n        grapheme += nextChar;\n        i++;\n      }\n    }\n  }\n\n  if (grapheme) {\n    if (zwjSequence) {\n      graphemes.push(zwjSequence + grapheme);\n    } else {\n      graphemes.push(grapheme);\n    }\n  }\n\n  return graphemes;\n}\n\nexport function skipTrailingNewLines(str: string): string {\n  return str.replace(/\\n+$/, '');\n}\n\n/**\n * Filters a string to include only specified characters, optionally replacing disallowed characters.\n *\n * @param str - The input string to be filtered.\n * @param list - An array of allowed characters.\n * @param caseInsensitive - Optional. If true, the filtering is case-insensitive. Default is false.\n * @param replacementChar - Optional. Character to replace disallowed characters. If empty, disallowed characters are removed. Default is ''.\n * @returns A new string containing only the allowed characters from the input string, with disallowed characters optionally replaced.\n *\n * @example\n * // Case-sensitive usage, removing disallowed characters\n * characterAllowedOnly(\"Hello123!\", [\"H\", \"e\", \"l\", \"o\"]);\n * // Returns: \"Hello\"\n *\n * @example\n * // Case-insensitive usage, removing disallowed characters\n * characterAllowedOnly(\"Hello123!\", [\"h\", \"E\", \"L\", \"O\"], true);\n * // Returns: \"Hello\"\n *\n * @example\n * // Using replacement character\n * characterAllowedOnly(\"Hello123!\", [\"H\", \"e\", \"l\", \"o\"], false, \"-\");\n * // Returns: \"Hello---\"\n */\n\nexport function characterAllowedOnly(\n  str: string,\n  list: string[],\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  caseInsensitive = false,\n  replacementChar = '',\n): string {\n  let newStr = '';\n\n  // Convert the allowed list to lowercase if case-insensitive\n  if (caseInsensitive) {\n    list = Array.from(new Set(list.map((item) => item.toLowerCase())));\n  }\n\n  // Convert the entire input string to lowercase if case-insensitive\n  const processedStr = caseInsensitive ? str.toLowerCase() : str;\n\n  for (const c of processedStr) {\n    if (list.includes(c)) {\n      newStr += c;\n    } else if (replacementChar !== '') {\n      newStr += replacementChar;\n    }\n  }\n\n  return newStr;\n}\n\n// functions to chop characters from a string.\n\n/**\n * Will remove the matching first character from a string\n * @param str\n * @param char\n * @returns\n */\n\nexport function chopBeginningCharacter(str: string, char: string): string {\n  if (str.startsWith(char)) {\n    return str.slice(1);\n  } else {\n    return str;\n  }\n}\n\n/**\n * Will remove the matching last character from the string\n * @param str\n * @param char\n * @returns\n */\nexport function chopEndingCharacter(str: string, char: string): string {\n  if (str.endsWith(char)) {\n    return str.slice(0, -1);\n  } else {\n    return str;\n  }\n}\n\n/**\n * Will remove the matching character, from the beginning and/or end of the string if matching\n * @param str\n * @param char\n * @returns\n */\n\nexport function chopBothBeginningAndEndingCharacters(\n  str: string,\n  char: string,\n): string {\n  return chopBeginningCharacter(chopEndingCharacter(str, char), char);\n}\n","import { isString } from './strings';\n\nexport function isArray(value: unknown): value is unknown[] {\n  return Array.isArray(value);\n}\n\nexport function removeEmptyStringsFromArray(array: string[]): string[] {\n  const newArray: string[] = [];\n\n  for (let item of array) {\n    item = item.trim();\n\n    if (item.length > 0) {\n      newArray.push(item);\n    }\n  }\n\n  return newArray;\n}\n\n/**\n * Will take an array and return a new array with a value prepended to each item\n *\n * @param array\n * @param value\n * @returns\n */\n\nexport function prependStringToArrayItems(\n  array: string[],\n  value: string,\n): string[] {\n  const newArray: string[] = [];\n\n  for (const item of array) {\n    newArray.push(value + item);\n  }\n\n  return newArray;\n}\n\nexport function isEveryArrayItemAnString(value: unknown): boolean {\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      if (!isString(item)) {\n        return false;\n      }\n    }\n\n    return true;\n  } else {\n    return false;\n  }\n}\n\nexport function areArraysEqual<T>(arr1: T[], arr2: T[]): boolean {\n  // Check if the arrays are the same length\n  if (arr1.length !== arr2.length) {\n    return false;\n  }\n\n  // Check each element in the arrays\n  for (const [i, element] of arr1.entries()) {\n    if (element !== arr2[i]) {\n      return false;\n    }\n  }\n\n  // If all elements are equal\n  return true;\n}\n\nexport function pushWithoutDuplicates(array: unknown[], value: unknown): void {\n  if (!array.includes(value)) {\n    array.push(value);\n  }\n}\n"],"mappings":";AAEO,SAAS,SAAS,OAAiC;AACxD,SAAO,OAAO,UAAU;AAC1B;;;ACFO,SAAS,QAAQ,OAAoC;AAC1D,SAAO,MAAM,QAAQ,KAAK;AAC5B;AAEO,SAAS,4BAA4B,OAA2B;AACrE,QAAM,WAAqB,CAAC;AAE5B,WAAS,QAAQ,OAAO;AACtB,WAAO,KAAK,KAAK;AAEjB,QAAI,KAAK,SAAS,GAAG;AACnB,eAAS,KAAK,IAAI;AAAA,IACpB;AAAA,EACF;AAEA,SAAO;AACT;AAUO,SAAS,0BACd,OACA,OACU;AACV,QAAM,WAAqB,CAAC;AAE5B,aAAW,QAAQ,OAAO;AACxB,aAAS,KAAK,QAAQ,IAAI;AAAA,EAC5B;AAEA,SAAO;AACT;AAEO,SAAS,yBAAyB,OAAyB;AAChE,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,eAAW,QAAQ,OAAO;AACxB,UAAI,CAAC,SAAS,IAAI,GAAG;AACnB,eAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO;AAAA,EACT,OAAO;AACL,WAAO;AAAA,EACT;AACF;AAEO,SAAS,eAAkB,MAAW,MAAoB;AAE/D,MAAI,KAAK,WAAW,KAAK,QAAQ;AAC/B,WAAO;AAAA,EACT;AAGA,aAAW,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,GAAG;AACzC,QAAI,YAAY,KAAK,CAAC,GAAG;AACvB,aAAO;AAAA,IACT;AAAA,EACF;AAGA,SAAO;AACT;AAEO,SAAS,sBAAsB,OAAkB,OAAsB;AAC5E,MAAI,CAAC,MAAM,SAAS,KAAK,GAAG;AAC1B,UAAM,KAAK,KAAK;AAAA,EAClB;AACF;","names":[]}