@gesslar/toolkit 0.5.0 → 0.7.0

package/src/lib/Util.js

@@ -62,6 +62,27 @@ export default class Util {
     return `${" ".repeat(diff)}${work}`
   }
 
+  /**
+   * Centre-align a string inside a fixed width (pad with spaces on left).
+   * If the string exceeds width it is returned unchanged.
+   *
+   * @param {string|number} text - Text to align.
+   * @param {number} width - Target field width (default 80).
+   * @returns {string} Padded string with text centred.
+   */
+  static centreAlignText(text, width=80) {
+    const work = String(text)
+
+    if(work.length >= width)
+      return work
+
+    const totalPadding = width - work.length
+    const leftPadding = Math.floor(totalPadding / 2)
+    const rightPadding = totalPadding - leftPadding
+
+    return `${" ".repeat(leftPadding)}${work}${" ".repeat(rightPadding)}`
+  }
+
   /**
    * Compute sha256 hash (hex) of the provided string.
    *
@@ -131,6 +152,67 @@ export default class Util {
     return await Promise.allSettled(promises)
   }
 
+  /**
+   * Checks if any result in the settled promise array is rejected.
+   *
+   * @param {Array<object>} result - Array of settled promise results.
+   * @returns {boolean} True if any result is rejected, false otherwise.
+   */
+  static anyRejected(result) {
+    return result.some(r => r.status === "rejected")
+  }
+
+  /**
+   * Filters and returns all rejected results from a settled promise array.
+   *
+   * @param {Array<object>} result - Array of settled promise results.
+   * @returns {Array<object>} Array of rejected results.
+   */
+  static settledAndRejected(result) {
+    return result.filter(r => r.status === "rejected")
+  }
+
+  /**
+   * Extracts the rejection reasons from an array of rejected promise results.
+   *
+   * @param {Array<object>} rejected - Array of rejected results.
+   * @returns {Array<unknown>} Array of rejection reasons.
+   */
+  static rejectedReasons(rejected) {
+    return rejected.map(r => r.reason)
+  }
+
+  /**
+   * Throws a Sass error containing all rejection reasons from settled promises.
+   *
+   * @param {string} [_message] - Optional error message. Defaults to "GIGO"
+   * @param {Array<object>} rejected - Array of rejected results.
+   * @throws {Error} Throws a Sass error with rejection reasons.
+   */
+  static throwRejected(_message="GIGO", rejected) {
+    throw Sass.new(Util.rejectedReasons(rejected))
+  }
+
+  /**
+   * Filters and returns all fulfilled results from a settled promise array.
+   *
+   * @param {Array<object>} result - Array of settled promise results.
+   * @returns {Array<object>} Array of fulfilled results.
+   */
+  static settledAndFulfilled(result) {
+    return result.filter(r => r.status === "fulfilled")
+  }
+
+  /**
+   * Extracts the values from all fulfilled results in a settled promise array.
+   *
+   * @param {Array<object>} result - Array of settled promise results.
+   * @returns {Array<unknown>} Array of fulfilled values.
+   */
+  static fulfilledValues(result) {
+    return this.settledAndFulfilled(result).map(r => r.value)
+  }
+
   /**
    * Returns the first promise to resolve or reject from an array of promises.
    * Wrapper around Promise.race for consistency with other utility methods.

package/src/lib/Valid.js

@@ -1,17 +1,27 @@
+/**
+ * @file Valid.js
+ *
+ * Provides validation utilities for type checking and assertion.
+ * Includes prototype pollution protection for secure object manipulation.
+ */
+
 import _assert from "node:assert/strict"
 
 import Sass from "./Sass.js"
 import Data from "./Data.js"
 import Collection from "./Collection.js"
 
-export default class Valid {
 /**
- * Validates a value against a type. Uses Data.isType.
- *
- * @param {unknown} value - The value to validate
- * @param {string} type - The expected type in the form of "object", "object[]", "object|object[]"
- * @param {object} [options] - Additional options for validation.
+ * Validation utility class providing type checking and assertion methods.
  */
+export default class Valid {
+  /**
+   * Validates a value against a type. Uses Data.isType.
+   *
+   * @param {unknown} value - The value to validate
+   * @param {string} type - The expected type in the form of "object", "object[]", "object|object[]"
+   * @param {object} [options] - Additional options for validation.
+   */
   static type(value, type, options) {
     Valid.assert(
       Data.isType(value, type, options),
@@ -48,6 +58,14 @@ export default class Valid {
   }
 
   static #restrictedProto = ["__proto__", "constructor", "prototype"]
+
+  /**
+   * Protects against prototype pollution by checking keys for dangerous property names.
+   * Throws if any restricted prototype properties are found in the keys array.
+   *
+   * @param {Array<string>} keys - Array of property keys to validate
+   * @throws {Sass} If any key matches restricted prototype properties (__proto__, constructor, prototype)
+   */
   static prototypePollutionProtection(keys) {
     Valid.type(keys, "String[]")
 

package/src/types/Collection.d.ts

@@ -211,7 +211,12 @@ export default class Collection {
   ): Promise<Record<string, R>>
 
   /** Allocate an object from a source array and spec */
-  static allocateObject(source: Array<unknown>, spec: Array<unknown> | ((source: Array<unknown>) => Promise<Array<unknown>> | Array<unknown>)): Promise<Record<string, unknown>>
+  static allocateObject(
+    source: Array<unknown>,
+    spec:
+      | Array<unknown>
+      | ((source: Array<unknown>) => Promise<Array<unknown>> | Array<unknown>)
+  ): Promise<Record<string, unknown>>
 
   /**
    * Flattens one level of an array of plain objects, transposing values so each

package/src/types/Contract.d.ts

@@ -11,18 +11,18 @@ export type DebugFunction = (message: string, level?: number, ...args: unknown[]
  * Contract represents a successful negotiation between Terms.
  * It handles validation and compatibility checking between what
  * one action provides and what another accepts.
- * 
+ *
  * @example
  * ```typescript
  * // Two-party contract between provider and consumer
  * const provider = new Terms(providerDefinition)
  * const consumer = new Terms(consumerDefinition)
  * const contract = new Contract(provider, consumer, { debug: console.log })
- * 
+ *
  * // Validate data against the contract
  * const isValid = contract.validate(someData)
  * ```
- * 
+ *
  * @example
  * ```typescript
  * // Single-party contract from terms definition
@@ -35,43 +35,43 @@ export type DebugFunction = (message: string, level?: number, ...args: unknown[]
  *     }
  *   }
  * })
- * 
+ *
  * contract.validate({ name: "John", age: 30 }) // true
  * ```
  */
 declare class Contract {
   /**
    * Creates a contract by negotiating between provider and consumer terms
-   * 
+   *
    * @param providerTerms - What the provider offers
-   * @param consumerTerms - What the consumer expects  
+   * @param consumerTerms - What the consumer expects
    * @param options - Configuration options
    * @param options.debug - Debug function for logging negotiation details
-   * 
+   *
    * @throws {Sass} If contract negotiation fails due to incompatible terms
    */
   constructor(
-    providerTerms: import('./Terms.js').default | null, 
-    consumerTerms: import('./Terms.js').default | null, 
+    providerTerms: import('./Terms.js').default | null,
+    consumerTerms: import('./Terms.js').default | null,
     options?: { debug?: DebugFunction }
   )
 
   /**
    * Creates a contract from terms with schema validation
-   * 
+   *
    * @param name - Contract identifier for error reporting
    * @param termsDefinition - The terms definition object
    * @param validator - Optional AJV schema validator function with .errors property
    * @param debug - Debug function for logging validation details
    * @returns New contract instance ready for data validation
-   * 
+   *
    * @throws {Sass} If terms definition is invalid according to the validator
-   * 
+   *
    * @example
    * ```typescript
    * const contract = Contract.fromTerms("user-parser", {
    *   provides: {
-   *     type: "object", 
+   *     type: "object",
    *     properties: {
    *       id: { type: "string" },
    *       name: { type: "string" }
@@ -82,22 +82,22 @@ declare class Contract {
    * ```
    */
   static fromTerms(
-    name: string, 
-    termsDefinition: object, 
-    validator?: ValidateFunction | null, 
+    name: string,
+    termsDefinition: object,
+    validator?: ValidateFunction | null,
     debug?: DebugFunction
   ): Contract
 
   /**
    * Validates data against this contract's schema
-   * 
+   *
    * @param data - Data object to validate against the contract
    * @returns True if validation passes
-   * 
+   *
    * @throws {Sass} If validation fails with detailed error messages
    * @throws {Sass} If contract has not been successfully negotiated
    * @throws {Sass} If no validator is available for this contract
-   * 
+   *
    * @example
    * ```typescript
    * try {
@@ -112,9 +112,9 @@ declare class Contract {
 
   /**
    * Check if contract negotiation was successful
-   * 
+   *
    * @returns True if the contract has been successfully negotiated
-   * 
+   *
    * @example
    * ```typescript
    * if (contract.isNegotiated) {
@@ -128,23 +128,23 @@ declare class Contract {
 
   /**
    * Get the provider terms (if any)
-   * 
+   *
    * @returns Provider terms or null for single-party contracts
    */
   get providerTerms(): import('./Terms.js').default | null
 
   /**
    * Get the consumer terms (if any)
-   * 
-   * @returns Consumer terms or null for single-party contracts  
+   *
+   * @returns Consumer terms or null for single-party contracts
    */
   get consumerTerms(): import('./Terms.js').default | null
 
   /**
    * Get the contract validator function
-   * 
+   *
    * @returns The AJV validator function used by this contract, or null if none available
-   * 
+   *
    * @example
    * ```typescript
    * const validator = contract.validator
@@ -159,4 +159,4 @@ declare class Contract {
   get validator(): ((data: object) => boolean) | null
 }
 
-export default Contract
+export default Contract

package/src/types/Data.d.ts

@@ -21,33 +21,33 @@ export default class Data {
 
   /**
    * Append a suffix string to the end of a string if it doesn't already end with it.
-   * 
-   * Useful for ensuring strings have consistent endings like file extensions, 
+   *
+   * Useful for ensuring strings have consistent endings like file extensions,
    * URL paths, or punctuation. Performs case-sensitive comparison and only appends
    * if the string doesn't already end with the specified suffix.
    *
    * @param string - The base string to potentially append to. Can be empty string.
    * @param append - The suffix to append if not already present. Cannot be empty.
    * @returns The string with the suffix appended, or the original string if suffix already present
-   * 
+   *
    * @throws {Error} When append parameter is empty or undefined
    *
    * @example
    * ```typescript
    * import { Data } from '@gesslar/toolkit'
-   * 
+   *
    * // Basic usage with file extensions
    * const filename = Data.appendString('config', '.json')
    * console.log(filename) // 'config.json'
-   * 
+   *
    * // No double-appending
-   * const alreadyHasExt = Data.appendString('package.json', '.json')  
+   * const alreadyHasExt = Data.appendString('package.json', '.json')
    * console.log(alreadyHasExt) // 'package.json' (unchanged)
-   * 
+   *
    * // URL path handling
    * const apiPath = Data.appendString('/api/users', '/')
    * console.log(apiPath) // '/api/users/'
-   * 
+   *
    * // Works with empty strings
    * const fromEmpty = Data.appendString('', '.txt')
    * console.log(fromEmpty) // '.txt'
@@ -57,33 +57,33 @@ export default class Data {
 
   /**
    * Prepend a prefix string to the beginning of a string if it doesn't already start with it.
-   * 
+   *
    * Useful for ensuring strings have consistent beginnings like protocol prefixes,
-   * path separators, or formatting markers. Performs case-sensitive comparison and 
+   * path separators, or formatting markers. Performs case-sensitive comparison and
    * only prepends if the string doesn't already start with the specified prefix.
    *
    * @param string - The base string to potentially prepend to. Can be empty string.
    * @param prepend - The prefix to prepend if not already present. Cannot be empty.
    * @returns The string with the prefix prepended, or the original string if prefix already present
-   * 
+   *
    * @throws {Error} When prepend parameter is empty or undefined
    *
    * @example
    * ```typescript
    * import { Data } from '@gesslar/toolkit'
-   * 
+   *
    * // Basic usage with protocols
    * const url = Data.prependString('example.com', 'https://')
    * console.log(url) // 'https://example.com'
-   * 
+   *
    * // No double-prepending
    * const alreadyHasProtocol = Data.prependString('https://api.example.com', 'https://')
    * console.log(alreadyHasProtocol) // 'https://api.example.com' (unchanged)
-   * 
+   *
    * // File path handling
    * const absolutePath = Data.prependString('home/user/docs', '/')
    * console.log(absolutePath) // '/home/user/docs'
-   * 
+   *
    * // CSS class prefixing
    * const className = Data.prependString('button-primary', 'css-')
    * console.log(className) // 'css-button-primary'
@@ -135,32 +135,32 @@ export default class Data {
   static clamped(val: number, min: number, max: number): boolean
 
   /**
-   * Checks if a value is a plain object - created with object literals {}, 
+   * Checks if a value is a plain object - created with object literals {},
    * new Object(), or Object.create(null).
-   * 
-   * Distinguishes plain objects from objects created by custom constructors, built-ins, 
+   *
+   * Distinguishes plain objects from objects created by custom constructors, built-ins,
    * or primitives. Plain objects only have Object.prototype or null in their prototype chain.
    * Useful for validating configuration objects or data structures that should be plain objects.
    *
    * @param value - The value to check for plain object status
    * @returns True if the value is a plain object, false otherwise
-   * 
+   *
    * @example
    * ```typescript
    * import { Data } from '@gesslar/toolkit'
-   * 
+   *
    * // Plain objects return true
    * console.log(Data.isPlainObject({})) // true
-   * console.log(Data.isPlainObject(new Object())) // true 
+   * console.log(Data.isPlainObject(new Object())) // true
    * console.log(Data.isPlainObject(Object.create(null))) // true
-   * 
+   *
    * // Non-plain objects return false
    * console.log(Data.isPlainObject([])) // false
    * console.log(Data.isPlainObject(new Date())) // false
    * console.log(Data.isPlainObject(/regex/)) // false
    * console.log(Data.isPlainObject(null)) // false
    * console.log(Data.isPlainObject('string')) // false
-   * 
+   *
    * // Useful for validating config objects
    * function processConfig(config: unknown) {
    *   if (!Data.isPlainObject(config)) {

package/src/types/FS.d.ts

@@ -9,13 +9,13 @@ import DirectoryObject from './DirectoryObject.js'
  */
 export default class FS {
   /** Array of lowercase file descriptor types */
-  static readonly fdTypes: readonly ["file", "directory"]
+  static readonly fdTypes: readonly ['file', 'directory']
 
   /** Array of uppercase file descriptor types */
-  static readonly upperFdTypes: readonly ["FILE", "DIRECTORY"]
+  static readonly upperFdTypes: readonly ['FILE', 'DIRECTORY']
 
   /** Mapping from uppercase to lowercase file descriptor types */
-  static readonly fdType: Readonly<Record<"FILE" | "DIRECTORY", "file" | "directory">>
+  static readonly fdType: Readonly<Record<'FILE' | 'DIRECTORY', 'file' | 'directory'>>
 
   /** Fix slashes in a path */
   static fixSlashes(pathName: string): string