@socketsecurity/lib 1.0.5 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2025-10-23
+
+### Added
+
+- Added `filterOutput` option to `stdio/mask` for filtering output chunks before display/buffering
+- Added `overrideExitCode` option to `stdio/mask` for customizing exit codes based on captured output
+- Added comprehensive JSDoc documentation across entire library for enhanced VSCode IntelliSense
+  - Detailed @param, @returns, @template, @throws tags
+  - Practical @example blocks with real-world usage patterns
+  - @default tags showing default values
+  - Enhanced interface property documentation
+
+### Changed
+
+- Improved TypeScript type hints and tooltips throughout library
+- Enhanced documentation for all core utilities (arrays, fs, git, github, http-request, json, logger, objects, path, promises, spawn, spinner, strings)
+- Enhanced documentation for stdio utilities (clear, divider, footer, header, mask, progress, prompts, stderr, stdout)
+- Enhanced documentation for validation utilities (json-parser, types)
+
 ## [1.0.5] - 2025-10-22
 
 ### Added

package/dist/arrays.d.ts

@@ -1,10 +1,63 @@
 /**
  * Split an array into chunks of a specified size.
+ *
+ * Divides an array into smaller arrays of the specified chunk size.
+ * The last chunk may contain fewer elements if the array length is not
+ * evenly divisible by the chunk size.
+ *
+ * @param arr - The array to split into chunks (can be readonly)
+ * @param size - Size of each chunk. Must be greater than 0.
+ * @default 2
+ * @returns Array of chunks, where each chunk is an array of elements
+ * @throws {Error} If chunk size is less than or equal to 0
+ *
+ * @example
+ * ```ts
+ * // Split into pairs (default)
+ * arrayChunk([1, 2, 3, 4, 5])
+ * // Returns: [[1, 2], [3, 4], [5]]
+ *
+ * // Split into groups of 3
+ * arrayChunk(['a', 'b', 'c', 'd', 'e', 'f', 'g'], 3)
+ * // Returns: [['a', 'b', 'c'], ['d', 'e', 'f'], ['g']]
+ *
+ * // Works with readonly arrays
+ * const readonlyArr = [1, 2, 3] as const
+ * arrayChunk(readonlyArr)
+ * // Returns: [[1, 2], [3]]
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function arrayChunk<T>(arr: T[] | readonly T[], size?: number | undefined): T[][];
 /**
  * Get unique values from an array.
+ *
+ * Returns a new array containing only the unique values from the input array.
+ * Uses `Set` internally for efficient deduplication. Order of first occurrence
+ * is preserved.
+ *
+ * @param arr - The array to deduplicate (can be readonly)
+ * @returns New array with duplicate values removed
+ *
+ * @example
+ * ```ts
+ * // Remove duplicate numbers
+ * arrayUnique([1, 2, 2, 3, 1, 4])
+ * // Returns: [1, 2, 3, 4]
+ *
+ * // Remove duplicate strings
+ * arrayUnique(['apple', 'banana', 'apple', 'cherry'])
+ * // Returns: ['apple', 'banana', 'cherry']
+ *
+ * // Works with readonly arrays
+ * const readonlyArr = [1, 1, 2] as const
+ * arrayUnique(readonlyArr)
+ * // Returns: [1, 2]
+ *
+ * // Empty arrays return empty
+ * arrayUnique([])
+ * // Returns: []
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function arrayUnique<T>(arr: T[] | readonly T[]): T[];
@@ -15,15 +68,105 @@ export declare function arrayUnique<T>(arr: T[] | readonly T[]): T[];
 /**
  * Alias for native Array.isArray.
  * Determines whether the passed value is an array.
+ *
+ * This is a direct reference to the native `Array.isArray` method,
+ * providing a type guard that narrows the type to an array type.
+ * Exported for consistency with other array utilities in this module.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is an array, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * // Check if value is an array
+ * isArray([1, 2, 3])
+ * // Returns: true
+ *
+ * isArray('not an array')
+ * // Returns: false
+ *
+ * isArray(null)
+ * // Returns: false
+ *
+ * // Type guard usage
+ * function processValue(value: unknown) {
+ *   if (isArray(value)) {
+ *     // TypeScript knows value is an array here
+ *     console.log(value.length)
+ *   }
+ * }
+ * ```
  */
 export declare const isArray: (arg: any) => arg is any[];
 /**
  * Join array elements with proper "and" conjunction formatting.
+ *
+ * Formats an array of strings into a grammatically correct list using
+ * "and" as the conjunction. Uses `Intl.ListFormat` for proper English
+ * formatting with Oxford comma support.
+ *
+ * @param arr - Array of strings to join (can be readonly)
+ * @returns Formatted string with proper "and" conjunction
+ *
+ * @example
+ * ```ts
+ * // Two items
+ * joinAnd(['apples', 'oranges'])
+ * // Returns: "apples and oranges"
+ *
+ * // Three or more items (Oxford comma)
+ * joinAnd(['apples', 'oranges', 'bananas'])
+ * // Returns: "apples, oranges, and bananas"
+ *
+ * // Single item
+ * joinAnd(['apples'])
+ * // Returns: "apples"
+ *
+ * // Empty array
+ * joinAnd([])
+ * // Returns: ""
+ *
+ * // Usage in messages
+ * const items = ['React', 'Vue', 'Angular']
+ * console.log(`You can choose ${joinAnd(items)}`)
+ * // Outputs: "You can choose React, Vue, and Angular"
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function joinAnd(arr: string[] | readonly string[]): string;
 /**
  * Join array elements with proper "or" disjunction formatting.
+ *
+ * Formats an array of strings into a grammatically correct list using
+ * "or" as the disjunction. Uses `Intl.ListFormat` for proper English
+ * formatting with Oxford comma support.
+ *
+ * @param arr - Array of strings to join (can be readonly)
+ * @returns Formatted string with proper "or" disjunction
+ *
+ * @example
+ * ```ts
+ * // Two items
+ * joinOr(['yes', 'no'])
+ * // Returns: "yes or no"
+ *
+ * // Three or more items (Oxford comma)
+ * joinOr(['red', 'green', 'blue'])
+ * // Returns: "red, green, or blue"
+ *
+ * // Single item
+ * joinOr(['maybe'])
+ * // Returns: "maybe"
+ *
+ * // Empty array
+ * joinOr([])
+ * // Returns: ""
+ *
+ * // Usage in prompts
+ * const options = ['npm', 'yarn', 'pnpm']
+ * console.log(`Choose a package manager: ${joinOr(options)}`)
+ * // Outputs: "Choose a package manager: npm, yarn, or pnpm"
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function joinOr(arr: string[] | readonly string[]): string;

package/dist/arrays.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/arrays.ts"],
-  "sourcesContent": ["/**\n * @fileoverview Array utility functions for formatting lists and collections.\n * Provides conjunction and disjunction formatters using Intl.ListFormat.\n */\n\nlet _conjunctionFormatter: Intl.ListFormat | undefined\n/**\n * Get a cached Intl.ListFormat instance for conjunction (and) formatting.\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getConjunctionFormatter() {\n  if (_conjunctionFormatter === undefined) {\n    _conjunctionFormatter = new Intl.ListFormat('en', {\n      style: 'long',\n      // \"and\" lists.\n      type: 'conjunction',\n    })\n  }\n  return _conjunctionFormatter\n}\n\nlet _disjunctionFormatter: Intl.ListFormat | undefined\n/**\n * Get a cached Intl.ListFormat instance for disjunction (or) formatting.\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getDisjunctionFormatter() {\n  if (_disjunctionFormatter === undefined) {\n    _disjunctionFormatter = new Intl.ListFormat('en', {\n      style: 'long',\n      // \"or\" lists.\n      type: 'disjunction',\n    })\n  }\n  return _disjunctionFormatter\n}\n\n/**\n * Split an array into chunks of a specified size.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function arrayChunk<T>(\n  arr: T[] | readonly T[],\n  size?: number | undefined,\n): T[][] {\n  const chunkSize = size ?? 2\n  if (chunkSize <= 0) {\n    throw new Error('Chunk size must be greater than 0')\n  }\n  const { length } = arr\n  const actualChunkSize = Math.min(length, chunkSize)\n  const chunks = []\n  for (let i = 0; i < length; i += actualChunkSize) {\n    chunks.push(arr.slice(i, i + actualChunkSize) as T[])\n  }\n  return chunks\n}\n\n/**\n * Get unique values from an array.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function arrayUnique<T>(arr: T[] | readonly T[]): T[] {\n  return [...new Set(arr)]\n}\n\n// IMPORTANT: Do not use destructuring here - use direct assignment instead.\n// tsgo has a bug that incorrectly transpiles destructured exports, resulting in\n// `exports.SomeName = void 0;` which causes runtime errors.\n// See: https://github.com/SocketDev/socket-packageurl-js/issues/3\n\n/**\n * Alias for native Array.isArray.\n * Determines whether the passed value is an array.\n */\nexport const isArray = Array.isArray\n\n/**\n * Join array elements with proper \"and\" conjunction formatting.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function joinAnd(arr: string[] | readonly string[]): string {\n  return getConjunctionFormatter().format(arr)\n}\n\n/**\n * Join array elements with proper \"or\" disjunction formatting.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function joinOr(arr: string[] | readonly string[]): string {\n  return getDisjunctionFormatter().format(arr)\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,IAAI;AAAA;AAMJ,SAAS,0BAA0B;AACjC,MAAI,0BAA0B,QAAW;AACvC,4BAAwB,IAAI,KAAK,WAAW,MAAM;AAAA,MAChD,OAAO;AAAA;AAAA,MAEP,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAEA,IAAI;AAAA;AAMJ,SAAS,0BAA0B;AACjC,MAAI,0BAA0B,QAAW;AACvC,4BAAwB,IAAI,KAAK,WAAW,MAAM;AAAA,MAChD,OAAO;AAAA;AAAA,MAEP,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAAA;AAMO,SAAS,WACd,KACA,MACO;AACP,QAAM,YAAY,QAAQ;AAC1B,MAAI,aAAa,GAAG;AAClB,UAAM,IAAI,MAAM,mCAAmC;AAAA,EACrD;AACA,QAAM,EAAE,OAAO,IAAI;AACnB,QAAM,kBAAkB,KAAK,IAAI,QAAQ,SAAS;AAClD,QAAM,SAAS,CAAC;AAChB,WAAS,IAAI,GAAG,IAAI,QAAQ,KAAK,iBAAiB;AAChD,WAAO,KAAK,IAAI,MAAM,GAAG,IAAI,eAAe,CAAQ;AAAA,EACtD;AACA,SAAO;AACT;AAAA;AAMO,SAAS,YAAe,KAA8B;AAC3D,SAAO,CAAC,GAAG,IAAI,IAAI,GAAG,CAAC;AACzB;AAWO,MAAM,UAAU,MAAM;AAAA;AAMtB,SAAS,QAAQ,KAA2C;AACjE,UAAO,wCAAwB,GAAE,OAAO,GAAG;AAC7C;AAAA;AAMO,SAAS,OAAO,KAA2C;AAChE,UAAO,wCAAwB,GAAE,OAAO,GAAG;AAC7C;",
+  "sourcesContent": ["/**\n * @fileoverview Array utility functions for formatting lists and collections.\n * Provides conjunction and disjunction formatters using Intl.ListFormat.\n */\n\nlet _conjunctionFormatter: Intl.ListFormat | undefined\n/**\n * Get a cached Intl.ListFormat instance for conjunction (and) formatting.\n *\n * Creates a singleton formatter for English \"and\" lists using the long style.\n * The formatter is lazily initialized on first use and reused for performance.\n *\n * @returns Cached Intl.ListFormat instance configured for conjunction formatting\n *\n * @example\n * ```ts\n * const formatter = getConjunctionFormatter()\n * formatter.format(['apple', 'banana', 'cherry'])\n * // Returns: \"apple, banana, and cherry\"\n * ```\n *\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getConjunctionFormatter() {\n  if (_conjunctionFormatter === undefined) {\n    _conjunctionFormatter = new Intl.ListFormat('en', {\n      style: 'long',\n      // \"and\" lists.\n      type: 'conjunction',\n    })\n  }\n  return _conjunctionFormatter\n}\n\nlet _disjunctionFormatter: Intl.ListFormat | undefined\n/**\n * Get a cached Intl.ListFormat instance for disjunction (or) formatting.\n *\n * Creates a singleton formatter for English \"or\" lists using the long style.\n * The formatter is lazily initialized on first use and reused for performance.\n *\n * @returns Cached Intl.ListFormat instance configured for disjunction formatting\n *\n * @example\n * ```ts\n * const formatter = getDisjunctionFormatter()\n * formatter.format(['red', 'blue', 'green'])\n * // Returns: \"red, blue, or green\"\n * ```\n *\n * @private\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getDisjunctionFormatter() {\n  if (_disjunctionFormatter === undefined) {\n    _disjunctionFormatter = new Intl.ListFormat('en', {\n      style: 'long',\n      // \"or\" lists.\n      type: 'disjunction',\n    })\n  }\n  return _disjunctionFormatter\n}\n\n/**\n * Split an array into chunks of a specified size.\n *\n * Divides an array into smaller arrays of the specified chunk size.\n * The last chunk may contain fewer elements if the array length is not\n * evenly divisible by the chunk size.\n *\n * @param arr - The array to split into chunks (can be readonly)\n * @param size - Size of each chunk. Must be greater than 0.\n * @default 2\n * @returns Array of chunks, where each chunk is an array of elements\n * @throws {Error} If chunk size is less than or equal to 0\n *\n * @example\n * ```ts\n * // Split into pairs (default)\n * arrayChunk([1, 2, 3, 4, 5])\n * // Returns: [[1, 2], [3, 4], [5]]\n *\n * // Split into groups of 3\n * arrayChunk(['a', 'b', 'c', 'd', 'e', 'f', 'g'], 3)\n * // Returns: [['a', 'b', 'c'], ['d', 'e', 'f'], ['g']]\n *\n * // Works with readonly arrays\n * const readonlyArr = [1, 2, 3] as const\n * arrayChunk(readonlyArr)\n * // Returns: [[1, 2], [3]]\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function arrayChunk<T>(\n  arr: T[] | readonly T[],\n  size?: number | undefined,\n): T[][] {\n  const chunkSize = size ?? 2\n  if (chunkSize <= 0) {\n    throw new Error('Chunk size must be greater than 0')\n  }\n  const { length } = arr\n  const actualChunkSize = Math.min(length, chunkSize)\n  const chunks = []\n  for (let i = 0; i < length; i += actualChunkSize) {\n    chunks.push(arr.slice(i, i + actualChunkSize) as T[])\n  }\n  return chunks\n}\n\n/**\n * Get unique values from an array.\n *\n * Returns a new array containing only the unique values from the input array.\n * Uses `Set` internally for efficient deduplication. Order of first occurrence\n * is preserved.\n *\n * @param arr - The array to deduplicate (can be readonly)\n * @returns New array with duplicate values removed\n *\n * @example\n * ```ts\n * // Remove duplicate numbers\n * arrayUnique([1, 2, 2, 3, 1, 4])\n * // Returns: [1, 2, 3, 4]\n *\n * // Remove duplicate strings\n * arrayUnique(['apple', 'banana', 'apple', 'cherry'])\n * // Returns: ['apple', 'banana', 'cherry']\n *\n * // Works with readonly arrays\n * const readonlyArr = [1, 1, 2] as const\n * arrayUnique(readonlyArr)\n * // Returns: [1, 2]\n *\n * // Empty arrays return empty\n * arrayUnique([])\n * // Returns: []\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function arrayUnique<T>(arr: T[] | readonly T[]): T[] {\n  return [...new Set(arr)]\n}\n\n// IMPORTANT: Do not use destructuring here - use direct assignment instead.\n// tsgo has a bug that incorrectly transpiles destructured exports, resulting in\n// `exports.SomeName = void 0;` which causes runtime errors.\n// See: https://github.com/SocketDev/socket-packageurl-js/issues/3\n\n/**\n * Alias for native Array.isArray.\n * Determines whether the passed value is an array.\n *\n * This is a direct reference to the native `Array.isArray` method,\n * providing a type guard that narrows the type to an array type.\n * Exported for consistency with other array utilities in this module.\n *\n * @param value - The value to check\n * @returns `true` if the value is an array, `false` otherwise\n *\n * @example\n * ```ts\n * // Check if value is an array\n * isArray([1, 2, 3])\n * // Returns: true\n *\n * isArray('not an array')\n * // Returns: false\n *\n * isArray(null)\n * // Returns: false\n *\n * // Type guard usage\n * function processValue(value: unknown) {\n *   if (isArray(value)) {\n *     // TypeScript knows value is an array here\n *     console.log(value.length)\n *   }\n * }\n * ```\n */\nexport const isArray = Array.isArray\n\n/**\n * Join array elements with proper \"and\" conjunction formatting.\n *\n * Formats an array of strings into a grammatically correct list using\n * \"and\" as the conjunction. Uses `Intl.ListFormat` for proper English\n * formatting with Oxford comma support.\n *\n * @param arr - Array of strings to join (can be readonly)\n * @returns Formatted string with proper \"and\" conjunction\n *\n * @example\n * ```ts\n * // Two items\n * joinAnd(['apples', 'oranges'])\n * // Returns: \"apples and oranges\"\n *\n * // Three or more items (Oxford comma)\n * joinAnd(['apples', 'oranges', 'bananas'])\n * // Returns: \"apples, oranges, and bananas\"\n *\n * // Single item\n * joinAnd(['apples'])\n * // Returns: \"apples\"\n *\n * // Empty array\n * joinAnd([])\n * // Returns: \"\"\n *\n * // Usage in messages\n * const items = ['React', 'Vue', 'Angular']\n * console.log(`You can choose ${joinAnd(items)}`)\n * // Outputs: \"You can choose React, Vue, and Angular\"\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function joinAnd(arr: string[] | readonly string[]): string {\n  return getConjunctionFormatter().format(arr)\n}\n\n/**\n * Join array elements with proper \"or\" disjunction formatting.\n *\n * Formats an array of strings into a grammatically correct list using\n * \"or\" as the disjunction. Uses `Intl.ListFormat` for proper English\n * formatting with Oxford comma support.\n *\n * @param arr - Array of strings to join (can be readonly)\n * @returns Formatted string with proper \"or\" disjunction\n *\n * @example\n * ```ts\n * // Two items\n * joinOr(['yes', 'no'])\n * // Returns: \"yes or no\"\n *\n * // Three or more items (Oxford comma)\n * joinOr(['red', 'green', 'blue'])\n * // Returns: \"red, green, or blue\"\n *\n * // Single item\n * joinOr(['maybe'])\n * // Returns: \"maybe\"\n *\n * // Empty array\n * joinOr([])\n * // Returns: \"\"\n *\n * // Usage in prompts\n * const options = ['npm', 'yarn', 'pnpm']\n * console.log(`Choose a package manager: ${joinOr(options)}`)\n * // Outputs: \"Choose a package manager: npm, yarn, or pnpm\"\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function joinOr(arr: string[] | readonly string[]): string {\n  return getDisjunctionFormatter().format(arr)\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,IAAI;AAAA;AAmBJ,SAAS,0BAA0B;AACjC,MAAI,0BAA0B,QAAW;AACvC,4BAAwB,IAAI,KAAK,WAAW,MAAM;AAAA,MAChD,OAAO;AAAA;AAAA,MAEP,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAEA,IAAI;AAAA;AAmBJ,SAAS,0BAA0B;AACjC,MAAI,0BAA0B,QAAW;AACvC,4BAAwB,IAAI,KAAK,WAAW,MAAM;AAAA,MAChD,OAAO;AAAA;AAAA,MAEP,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAAA;AAgCO,SAAS,WACd,KACA,MACO;AACP,QAAM,YAAY,QAAQ;AAC1B,MAAI,aAAa,GAAG;AAClB,UAAM,IAAI,MAAM,mCAAmC;AAAA,EACrD;AACA,QAAM,EAAE,OAAO,IAAI;AACnB,QAAM,kBAAkB,KAAK,IAAI,QAAQ,SAAS;AAClD,QAAM,SAAS,CAAC;AAChB,WAAS,IAAI,GAAG,IAAI,QAAQ,KAAK,iBAAiB;AAChD,WAAO,KAAK,IAAI,MAAM,GAAG,IAAI,eAAe,CAAQ;AAAA,EACtD;AACA,SAAO;AACT;AAAA;AAiCO,SAAS,YAAe,KAA8B;AAC3D,SAAO,CAAC,GAAG,IAAI,IAAI,GAAG,CAAC;AACzB;AAuCO,MAAM,UAAU,MAAM;AAAA;AAqCtB,SAAS,QAAQ,KAA2C;AACjE,UAAO,wCAAwB,GAAE,OAAO,GAAG;AAC7C;AAAA;AAqCO,SAAS,OAAO,KAA2C;AAChE,UAAO,wCAAwB,GAAE,OAAO,GAAG;AAC7C;",
   "names": []
 }