@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/argv/flag-types.js

@@ -0,0 +1,116 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"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);
+var flag_types_exports = {};
+__export(flag_types_exports, {
+  COMMON_FLAGS: () => COMMON_FLAGS
+});
+module.exports = __toCommonJS(flag_types_exports);
+const COMMON_FLAGS = {
+  all: {
+    type: "boolean",
+    default: false,
+    description: "Target all files"
+  },
+  changed: {
+    type: "boolean",
+    default: false,
+    description: "Target changed files"
+  },
+  coverage: {
+    type: "boolean",
+    default: false,
+    description: "Run with coverage"
+  },
+  cover: {
+    type: "boolean",
+    default: false,
+    description: "Run with coverage (alias)"
+  },
+  debug: {
+    type: "boolean",
+    default: false,
+    description: "Enable debug output"
+  },
+  "dry-run": {
+    type: "boolean",
+    default: false,
+    description: "Perform a dry run"
+  },
+  fix: {
+    type: "boolean",
+    default: false,
+    description: "Automatically fix issues"
+  },
+  force: {
+    type: "boolean",
+    default: false,
+    description: "Force the operation"
+  },
+  help: {
+    type: "boolean",
+    default: false,
+    short: "h",
+    description: "Show help"
+  },
+  json: {
+    type: "boolean",
+    default: false,
+    description: "Output as JSON"
+  },
+  quiet: {
+    type: "boolean",
+    default: false,
+    short: "q",
+    description: "Suppress output"
+  },
+  silent: {
+    type: "boolean",
+    default: false,
+    description: "Suppress all output"
+  },
+  staged: {
+    type: "boolean",
+    default: false,
+    description: "Target staged files"
+  },
+  update: {
+    type: "boolean",
+    default: false,
+    short: "u",
+    description: "Update snapshots/deps"
+  },
+  verbose: {
+    type: "boolean",
+    default: false,
+    short: "v",
+    description: "Verbose output"
+  },
+  watch: {
+    type: "boolean",
+    default: false,
+    short: "w",
+    description: "Watch mode"
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  COMMON_FLAGS
+});

package/dist/argv/parse.d.ts

@@ -1,7 +1,7 @@
 /**
- * @fileoverview Argument parsing utilities for CLI applications.
- * Wraps the vendored yargs-parser with a Node.js parseArgs-compatible surface
- * for booleans, strings, arrays, aliases, defaults, and coercion.
+ * @file Argument parsing utilities for CLI applications. Wraps the vendored
+ *   yargs-parser with a Node.js parseArgs-compatible surface for booleans,
+ *   strings, arrays, aliases, defaults, and coercion.
  */
 /**
  * Yargs parser result interface.
@@ -21,7 +21,8 @@ export interface ParseArgsOptionsConfig {
     coerce?: (value: unknown) => unknown | undefined;
 }
 /**
- * Configuration object for parseArgs function, similar to Node.js util.parseArgs.
+ * Configuration object for parseArgs function, similar to Node.js
+ * util.parseArgs.
  */
 export interface ParseArgsConfig {
     args?: readonly string[] | undefined;
@@ -45,53 +46,53 @@ export interface ParsedArgs<T = Record<string, unknown>> {
  */
 export declare const commonParseArgsConfig: ParseArgsConfig;
 /**
- * Extract positional arguments from process.argv.
- * Useful for commands that accept file paths or other positional parameters.
+ * Extract positional arguments from process.argv. Useful for commands that
+ * accept file paths or other positional parameters.
  *
  * @example
- * ```typescript
- * // process.argv = ["node", "script.js", "src", "lib", "--verbose"]
- * getPositionalArgs()  // ["src", "lib"]
- * ```
+ *   ;```typescript
+ *   // process.argv = ["node", "script.js", "src", "lib", "--verbose"]
+ *   getPositionalArgs() // ["src", "lib"]
+ *   ```
  */
 export declare function getPositionalArgs(startIndex?: number): string[];
 /**
  * Check if a specific flag is present in argv.
  *
  * @example
- * ```typescript
- * hasFlag('verbose')  // true if --verbose is in process.argv
- * hasFlag('force', ['--force', '--quiet'])  // true
- * ```
+ *   ;```typescript
+ *   hasFlag('verbose') // true if --verbose is in process.argv
+ *   hasFlag('force', ['--force', '--quiet']) // true
+ *   ```
  */
 export declare function hasFlag(flag: string, argv?: string[]): boolean;
 /**
- * Parse command-line arguments with a Node.js parseArgs-compatible API.
- * Uses yargs-parser internally for robust argument parsing.
+ * Parse command-line arguments with a Node.js parseArgs-compatible API. Uses
+ * yargs-parser internally for robust argument parsing.
  *
  * @example
- * ```typescript
- * const { values, positionals } = parseArgs({
- *   args: ['--force', '--quiet', 'file.ts'],
- *   options: {
- *     force: { type: 'boolean' },
- *     quiet: { type: 'boolean', short: 'q' },
- *   },
- * })
- * ```
+ *   ;```typescript
+ *   const { values, positionals } = parseArgs({
+ *     args: ['--force', '--quiet', 'file.ts'],
+ *     options: {
+ *       force: { type: 'boolean' },
+ *       quiet: { type: 'boolean', short: 'q' },
+ *     },
+ *   })
+ *   ```
  */
 export declare function parseArgs<T = Record<string, unknown>>(config?: ParseArgsConfig): ParsedArgs<T>;
 /**
- * Parse command-line arguments with Socket defaults.
- * Provides sensible defaults for Socket CLI applications.
+ * Parse command-line arguments with Socket defaults. Provides sensible defaults
+ * for Socket CLI applications.
  *
  * @example
- * ```typescript
- * const { values, positionals } = parseArgsWithDefaults({
- *   args: ['--force', 'file.ts'],
- *   options: { force: { type: 'boolean' } },
- * })
- * ```
+ *   ;```typescript
+ *   const { values, positionals } = parseArgsWithDefaults({
+ *     args: ['--force', 'file.ts'],
+ *     options: { force: { type: 'boolean' } },
+ *   })
+ *   ```
  */
 export declare function parseArgsWithDefaults<T = Record<string, unknown>>(config?: ParseArgsConfig): ParsedArgs<T>;
 export {};

package/dist/argv/parse.js

@@ -39,7 +39,9 @@ __export(parse_exports, {
 module.exports = __toCommonJS(parse_exports);
 var import_node_process = __toESM(require("node:process"));
 var import_yargs_parser = __toESM(require("../external/yargs-parser"));
-var import_primordials = require("../primordials");
+var import_array = require("../primordials/array");
+var import_object = require("../primordials/object");
+var import_string = require("../primordials/string");
 const commonParseArgsConfig = {
   options: {
     force: {
@@ -61,7 +63,7 @@ function getPositionalArgs(startIndex = 2) {
   let i = 0;
   while (i < args.length) {
     const arg = args[i];
-    if ((0, import_primordials.StringPrototypeStartsWith)(arg, "-")) {
+    if ((0, import_string.StringPrototypeStartsWith)(arg, "-")) {
       break;
     }
     positionals.push(arg);
@@ -70,7 +72,7 @@ function getPositionalArgs(startIndex = 2) {
   return positionals;
 }
 function hasFlag(flag, argv = import_node_process.default.argv) {
-  return (0, import_primordials.ArrayPrototypeIncludes)(argv, `--${flag}`);
+  return (0, import_array.ArrayPrototypeIncludes)(argv, `--${flag}`);
 }
 function parseArgs(config = {}) {
   const {
@@ -115,7 +117,7 @@ function parseArgs(config = {}) {
       ...configuration
     }
   };
-  for (const { 0: key, 1: optionConfig } of (0, import_primordials.ObjectEntries)(options)) {
+  for (const { 0: key, 1: optionConfig } of (0, import_object.ObjectEntries)(options)) {
     const {
       coerce,
       default: defaultValue,

package/dist/arrays/_internal.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @file Private internals for `arrays/*` modules — cached `Intl.ListFormat`
+ *   instances for conjunction (and) and disjunction (or) joins. Constructed
+ *   lazily because `new Intl.ListFormat(...)` is a measurable startup cost.
+ */
+/**
+ * Get a cached Intl.ListFormat instance for conjunction (and) formatting.
+ *
+ * Creates a singleton formatter for English "and" lists using the long style.
+ * The formatter is lazily initialized on first use and reused for performance.
+ *
+ * @private
+ *
+ * @example
+ *   ;```ts
+ *   const formatter = getConjunctionFormatter()
+ *   formatter.format(['apple', 'banana', 'cherry'])
+ *   // Returns: "apple, banana, and cherry"
+ *   ```
+ *
+ * @returns Cached Intl.ListFormat instance configured for conjunction
+ *   formatting.
+ */
+export declare function getConjunctionFormatter(): Intl.ListFormat;
+/**
+ * Get a cached Intl.ListFormat instance for disjunction (or) formatting.
+ *
+ * Creates a singleton formatter for English "or" lists using the long style.
+ * The formatter is lazily initialized on first use and reused for performance.
+ *
+ * @private
+ *
+ * @example
+ *   ;```ts
+ *   const formatter = getDisjunctionFormatter()
+ *   formatter.format(['red', 'blue', 'green'])
+ *   // Returns: "red, blue, or green"
+ *   ```
+ *
+ * @returns Cached Intl.ListFormat instance configured for disjunction
+ *   formatting.
+ */
+export declare function getDisjunctionFormatter(): Intl.ListFormat;

package/dist/{arrays.js → arrays/_internal.js}

@@ -18,17 +18,14 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var arrays_exports = {};
-__export(arrays_exports, {
-  arrayChunk: () => arrayChunk,
-  arrayUnique: () => arrayUnique,
-  isArray: () => isArray,
-  joinAnd: () => joinAnd,
-  joinOr: () => joinOr
+var internal_exports = {};
+__export(internal_exports, {
+  getConjunctionFormatter: () => getConjunctionFormatter,
+  getDisjunctionFormatter: () => getDisjunctionFormatter
 });
-module.exports = __toCommonJS(arrays_exports);
-var import_primordials = require("./primordials");
+module.exports = __toCommonJS(internal_exports);
 let _conjunctionFormatter;
+let _disjunctionFormatter;
 // @__NO_SIDE_EFFECTS__
 function getConjunctionFormatter() {
   if (_conjunctionFormatter === void 0) {
@@ -40,7 +37,6 @@ function getConjunctionFormatter() {
   }
   return _conjunctionFormatter;
 }
-let _disjunctionFormatter;
 // @__NO_SIDE_EFFECTS__
 function getDisjunctionFormatter() {
   if (_disjunctionFormatter === void 0) {
@@ -52,37 +48,8 @@ function getDisjunctionFormatter() {
   }
   return _disjunctionFormatter;
 }
-// @__NO_SIDE_EFFECTS__
-function arrayChunk(arr, size) {
-  const chunkSize = size ?? 2;
-  if (chunkSize <= 0) {
-    throw new import_primordials.ErrorCtor("Chunk size must be greater than 0");
-  }
-  const { length } = arr;
-  const chunks = [];
-  for (let i = 0; i < length; i += chunkSize) {
-    chunks.push(arr.slice(i, i + chunkSize));
-  }
-  return chunks;
-}
-// @__NO_SIDE_EFFECTS__
-function arrayUnique(arr) {
-  return [...new import_primordials.SetCtor(arr)];
-}
-const isArray = Array.isArray;
-// @__NO_SIDE_EFFECTS__
-function joinAnd(arr) {
-  return (/* @__PURE__ */ getConjunctionFormatter()).format(arr);
-}
-// @__NO_SIDE_EFFECTS__
-function joinOr(arr) {
-  return (/* @__PURE__ */ getDisjunctionFormatter()).format(arr);
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  arrayChunk,
-  arrayUnique,
-  isArray,
-  joinAnd,
-  joinOr
+  getConjunctionFormatter,
+  getDisjunctionFormatter
 });

package/dist/arrays/chunk.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file Split an array into fixed-size chunks. The last chunk holds the
+ *   leftover when length is not evenly divisible.
+ */
+/**
+ * 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.
+ *
+ * @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]]
+ *   ```
+ *
+ * @default 2
+ *
+ * @param arr - The array to split into chunks (can be readonly)
+ * @param size - Size of each chunk. Must be greater than 0.
+ *
+ * @returns Array of chunks, where each chunk is an array of elements
+ *
+ * @throws {Error} If chunk size is less than or equal to 0
+ */
+export declare function arrayChunk<T>(arr: T[] | readonly T[], size?: number | undefined): T[][];

package/dist/arrays/chunk.js

@@ -0,0 +1,43 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"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);
+var chunk_exports = {};
+__export(chunk_exports, {
+  arrayChunk: () => arrayChunk
+});
+module.exports = __toCommonJS(chunk_exports);
+var import_error = require("../primordials/error");
+// @__NO_SIDE_EFFECTS__
+function arrayChunk(arr, size) {
+  const chunkSize = size ?? 2;
+  if (chunkSize <= 0) {
+    throw new import_error.ErrorCtor("Chunk size must be greater than 0");
+  }
+  const { length } = arr;
+  const chunks = [];
+  for (let i = 0; i < length; i += chunkSize) {
+    chunks.push(arr.slice(i, i + chunkSize));
+  }
+  return chunks;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  arrayChunk
+});

package/dist/arrays/join.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @file Grammatical list joiners via `Intl.ListFormat` — Oxford-comma aware and
+ *   locale-correct. `joinAnd` ("a, b, and c"), `joinOr` ("a, b, or c").
+ */
+/**
+ * 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.
+ *
+ * @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"
+ *   ```
+ *
+ * @param arr - Array of strings to join (can be readonly)
+ *
+ * @returns Formatted string with proper "and" conjunction
+ */
+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.
+ *
+ * @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"
+ *   ```
+ *
+ * @param arr - Array of strings to join (can be readonly)
+ *
+ * @returns Formatted string with proper "or" disjunction
+ */
+export declare function joinOr(arr: string[] | readonly string[]): string;

package/dist/{env/helpers.js → arrays/join.js}

@@ -18,29 +18,23 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var helpers_exports = {};
-__export(helpers_exports, {
-  envAsBoolean: () => envAsBoolean,
-  envAsNumber: () => envAsNumber,
-  envAsString: () => envAsString
+var join_exports = {};
+__export(join_exports, {
+  joinAnd: () => joinAnd,
+  joinOr: () => joinOr
 });
-module.exports = __toCommonJS(helpers_exports);
-var import_env = require("../env");
+module.exports = __toCommonJS(join_exports);
+var import_internal = require("./_internal");
 // @__NO_SIDE_EFFECTS__
-function envAsBoolean(value) {
-  return (0, import_env.envAsBoolean)(value, { trim: false });
+function joinAnd(arr) {
+  return (0, import_internal.getConjunctionFormatter)().format(arr);
 }
 // @__NO_SIDE_EFFECTS__
-function envAsNumber(value) {
-  return (0, import_env.envAsNumber)(value, { mode: "float", allowInfinity: true });
-}
-// @__NO_SIDE_EFFECTS__
-function envAsString(value) {
-  return (0, import_env.envAsString)(value, { trim: false });
+function joinOr(arr) {
+  return (0, import_internal.getDisjunctionFormatter)().format(arr);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  envAsBoolean,
-  envAsNumber,
-  envAsString
+  joinAnd,
+  joinOr
 });

package/dist/arrays/predicates.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Array type-guard predicates. Currently just a re-export of native
+ *   `Array.isArray` for consistency with the rest of the arrays surface — kept
+ *   in its own leaf because it's runtime-trivial but conceptually a different
+ *   concern from `chunk` / `unique` / `join`.
+ */
+/**
+ * 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.
+ *
+ * @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)
+ *     }
+ *   }
+ *   ```
+ *
+ * @param value - The value to check.
+ *
+ * @returns `true` if the value is an array, `false` otherwise
+ */
+export declare const isArray: (arg: any) => arg is any[];

package/dist/arrays/predicates.js

@@ -0,0 +1,30 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"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);
+var predicates_exports = {};
+__export(predicates_exports, {
+  isArray: () => isArray
+});
+module.exports = __toCommonJS(predicates_exports);
+const isArray = Array.isArray;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isArray
+});

package/dist/arrays/unique.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file Deduplicate an array via `Set`. Preserves
+ * first-occurrence order.
+ */
+/**
+ * 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.
+ *
+ * @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: []
+ *   ```
+ *
+ * @param arr - The array to deduplicate (can be readonly)
+ *
+ * @returns New array with duplicate values removed
+ */
+export declare function arrayUnique<T>(arr: T[] | readonly T[]): T[];