@plyaz/types 1.5.4 → 1.6.0

package/dist/testing/common/factories/types.d.ts

@@ -779,3 +779,19 @@ export interface TrackedMockFunction<TArgs extends unknown[], TReturn> extends V
     /** Reset all tracked calls */
     resetCalls: () => void;
 }
+/**
+ * Type for array assertion predicates with void support
+ */
+export type ArrayPredicate<T> = (item: T, index?: number, array?: T[]) => boolean | void;
+/**
+ * Enhanced object shape validation type
+ */
+export type ObjectShape<T> = Partial<Record<keyof T, 'string' | 'number' | 'boolean' | 'object' | 'function' | 'undefined' | 'symbol'>>;
+/**
+ * Pattern matching type for object assertions
+ */
+export type ObjectPattern<T> = {
+    [K in keyof T]?: T[K] | RegExp | ((value: unknown) => boolean) | {
+        asymmetricMatch(value: unknown): boolean;
+    };
+};

package/dist/testing/common/utils/types.d.ts

@@ -1243,12 +1243,27 @@ export interface WaitForChangeOptions<T> {
  * ```
  */
 export interface PerformanceMetrics {
+    /** Minimum execution time (ms) */
     min: number;
+    /** Maximum execution time (ms) */
     max: number;
+    /** Operations per second */
+    opsPerSecond: number;
+    /** Mean execution time (ms) */
     mean: number;
+    /** Median execution time (ms) */
     median: number;
+    /** Standard deviation of execution times */
+    stdDev: number;
+    /** 95th percentile execution time (ms) */
     p95: number;
+    /** 99th percentile execution time (ms) */
     p99: number;
+    /**
+     * Array of all duration measurements (ms)
+     * @remarks This is actually an array of durations, not the count of runs
+     * The naming is inconsistent but matches the current implementation
+     */
     runs: number[];
 }
 /**
@@ -1300,7 +1315,33 @@ export interface MeasureTimeResult<T> {
  * ```
  */
 export interface BenchmarkResult {
-    [functionName: string]: PerformanceMetrics;
+    /** Name of the benchmark suite */
+    name: string;
+    /**
+     * Performance metrics for each benchmarked operation
+     * @remarks Keys are the function names from the input functions object
+     */
+    operations: Record<string, PerformanceMetrics>;
+    /**
+     * Timestamp when benchmark was run
+     * @optional
+     */
+    timestamp?: number;
+    /**
+     * Total duration of all benchmark runs (ms)
+     * @optional
+     */
+    totalDuration?: number;
+    /**
+     * Comparison data between operations
+     * @optional
+     */
+    comparison?: {
+        fastest: string;
+        slowest: string;
+        /** Relative performance (fastest = 1.0) */
+        relative: Record<string, number>;
+    };
 }
 /**
  * Options for load testing.
@@ -1525,12 +1566,45 @@ export interface PerformanceComparisonInput<T> {
  *   peak: 60 * 1024 * 1024    // 60MB peak
  * };
  * ```
+ * @remarks
+ * Added `used` and `heapUsed` properties for better compatibility
+ * and clearer API. The `heapUsed` property provides compatibility
+ * with Node.js memory usage conventions.
  */
 export interface MemoryMeasurement {
+    /** Memory usage before operation (bytes) */
     before: number;
+    /** Memory usage after operation (bytes) */
     after: number;
+    /** Change in memory usage (after - before) in bytes */
     delta: number;
+    /** Peak memory usage during operation (bytes) */
     peak: number;
+    /**
+     * Memory used by operation (bytes)
+     * @remarks Alias for delta, provides clearer semantic meaning
+     */
+    used: number;
+    /**
+     * Heap memory used by operation (bytes)
+     * @remarks Alias for delta, provides Node.js compatibility
+     */
+    heapUsed: number;
+    /**
+     * Total heap size (bytes)
+     * @optional Additional memory information when available
+     */
+    heapTotal?: number;
+    /**
+     * External memory usage (bytes)
+     * @optional V8 external memory when available
+     */
+    external?: number;
+    /**
+     * Resident set size (bytes)
+     * @optional Total memory allocated for the process
+     */
+    rss?: number;
 }
 /**
  * Options for memory measurement during testing.
@@ -1549,8 +1623,27 @@ export interface MemoryMeasurement {
  * ```
  */
 export interface MeasureMemoryOptions {
+    /**
+     * Force garbage collection before measurement
+     * @default false
+     * @remarks Requires --expose-gc flag in Node.js
+     */
     forceGC?: boolean;
+    /**
+     * Number of measurement runs to average
+     * @default 1
+     */
     runs?: number;
+    /**
+     * Run garbage collection between each measurement
+     * @default false
+     */
+    gcBetweenRuns?: boolean;
+    /**
+     * Include detailed heap statistics
+     * @default false
+     */
+    detailed?: boolean;
 }
 /**
  * Result from memory measurement testing.
@@ -2401,9 +2494,24 @@ export interface ImageLoaderProps {
     width: number;
     quality?: number;
 }
+/**
+ * Global type augmentation for performance.memory
+ *
+ * @remarks
+ * Extends the Performance interface to include memory property
+ * available in Chrome and Node.js environments
+ */
 export interface PerformanceMemory {
+    /**
+     * Performance object with memory property
+     */
     memory?: {
+        /** Used JS heap size in bytes */
         usedJSHeapSize: number;
+        /** Total JS heap size in bytes */
+        totalJSHeapSize: number;
+        /** JS heap size limit in bytes */
+        jsHeapSizeLimit: number;
     };
 }
 export interface NextPageResult {
@@ -3018,7 +3126,9 @@ export interface PerformanceEntryResult {
  * ```
  */
 export interface MemoryMeasurementResult<T> {
+    /** Single measurement data */
     measurement: MemoryMeasurement;
+    /** Function execution result */
     result: T;
 }
 /**
@@ -3034,6 +3144,10 @@ export interface MemoryMeasurementResult<T> {
  * ```
  */
 export interface GlobalWithGC {
+    /**
+     * Manual garbage collection trigger
+     * @remarks Only available with --expose-gc flag
+     */
     gc?: () => void;
 }
 /**
@@ -5651,7 +5765,7 @@ export interface FileSnapshot {
  * Environment configuration
  * @interface EnvConfig
  */
-interface EnvConfig {
+export interface EnvConfig {
     baseDir?: string;
     envFile?: string;
     override?: boolean;
@@ -5755,4 +5869,67 @@ export interface AsyncHook {
     after?: (asyncId: number) => void;
     destroy?: (asyncId: number) => void;
 }
-export {};
+/**
+ * JSON parsing options for safe parsing
+ */
+export interface JSONParseOptions {
+    /**
+     * Custom reviver function
+     * @remarks Called after prototype pollution filtering
+     */
+    reviver?: (key: string, value: unknown) => unknown;
+    /**
+     * Allow parsing of Date strings
+     * @default false
+     */
+    parseDates?: boolean;
+    /**
+     * Additional keys to filter out during parsing
+     * @default []
+     */
+    filterKeys?: string[];
+}
+/**
+ * JSON stringify options for safe stringification
+ */
+export interface JSONStringifyOptions {
+    /**
+     * Indentation (number of spaces or string)
+     */
+    space?: string | number;
+    /**
+     * Custom replacer function
+     */
+    replacer?: (key: string, value: unknown) => unknown;
+    /**
+     * Custom circular reference placeholder
+     * @default "[Circular]"
+     */
+    circularPlaceholder?: string;
+    /**
+     * Maximum depth for nested objects
+     * @default Infinity
+     */
+    maxDepth?: number;
+}
+/**
+ * JSON utilities interface
+ */
+export interface JSONUtils {
+    /**
+     * Safely parse JSON with prototype pollution prevention
+     */
+    parse(json: string, options?: JSONParseOptions): unknown;
+    /**
+     * Safely stringify objects handling circular references
+     */
+    stringify(obj: unknown, options?: JSONStringifyOptions | string | number): string;
+    /**
+     * Check if a string is valid JSON
+     */
+    isValid?(json: string): boolean;
+    /**
+     * Deep clone an object using JSON
+     */
+    clone?<T>(obj: T): T;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.5.4",
+  "version": "1.6.0",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",