@pawells/typescript-common 1.0.1 → 1.1.1

package/build/array/assert.js

@@ -0,0 +1,182 @@
+import { SetExceptionClass, SetExceptionMessage, ThrowException } from '../asserts/utils.js';
+/**
+ * Error thrown when a value is not a valid array or fails an array assertion.
+ *
+ * @example
+ * throw new ArrayError('Value is not a valid array');
+ */
+export class ArrayError extends Error {
+    constructor(message) {
+        super(message ?? 'Array assertion failed');
+        this.name = 'ArrayError';
+        Object.setPrototypeOf(this, ArrayError.prototype);
+    }
+}
+/**
+ * Asserts that a value is an array, optionally validating its size.
+ * @template T The type of array elements.
+ * @param value The value to validate.
+ * @param args Optional size constraints.
+ * @param exception Optional custom exception to throw.
+ * @throws {ArrayError} If the value is not an array or fails size validation.
+ */
+export function AssertArray(value, args, exceptionInput = {}) {
+    // Initialize exception configuration with defaults
+    const exception = exceptionInput ?? {};
+    SetExceptionClass(exception, ArrayError);
+    // Validate that the value is an array
+    if (!Array.isArray(value)) {
+        SetExceptionMessage(exception, `Expected array but received ${typeof value}: ${String(value)}`);
+        ThrowException(exception);
+    }
+    // Type cast is safe after array validation
+    const array = value;
+    // Validate exact size constraint if specified
+    if (args?.size !== undefined && array.length !== args.size) {
+        SetExceptionMessage(exception, `Expected array with size ${args.size} but received size ${array.length}`);
+        ThrowException(exception);
+    }
+    // Validate minimum size constraint if specified
+    if (args?.minSize !== undefined && array.length < args.minSize) {
+        SetExceptionMessage(exception, `Expected array with minimum size ${args.minSize} but received size ${array.length}`);
+        ThrowException(exception);
+    }
+    // Validate maximum size constraint if specified
+    if (args?.maxSize !== undefined && array.length > args.maxSize) {
+        SetExceptionMessage(exception, `Expected array with maximum size ${args.maxSize} but received size ${array.length}`);
+        ThrowException(exception);
+    }
+}
+/**
+ * Asserts that a value is a 2D array, optionally validating its dimensions.
+ * @template T The type of array elements.
+ * @param value The value to validate.
+ * @param args Optional dimension constraints.
+ * @param exception Optional custom exception to throw.
+ * @throws {ArrayError} If the value is not a 2D array or fails dimension validation.
+ */
+export function AssertArray2D(value, args = {}, exception = {}) {
+    // Initialize exception configuration with defaults
+    SetExceptionClass(exception, ArrayError);
+    // Validate that the value is an array
+    if (!Array.isArray(value)) {
+        SetExceptionMessage(exception, `Expected array but received ${typeof value}: ${String(value)}`);
+        ThrowException(exception);
+    }
+    // Type cast is safe after array validation
+    const array = value;
+    // Validate that all elements are arrays (making it 2D)
+    if (!array.every((row) => Array.isArray(row))) {
+        let invalidPositions = array.map((row, idx) => {
+            if (!Array.isArray(row))
+                return idx;
+            return null;
+        });
+        invalidPositions = invalidPositions.filter((idx) => idx !== null);
+        SetExceptionMessage(exception, `Expected 2D array but found non-array elements at positions: ${invalidPositions.join(', ')}`);
+        ThrowException(exception);
+    }
+    // Type cast is safe after 2D validation
+    const array2d = array;
+    const rows = array2d.length;
+    const [firstRow] = array2d;
+    const columns = firstRow ? firstRow.length : 0;
+    // Validate rectangular matrix structure (all rows have same column count)
+    if (!array2d.every((row) => row.length === columns)) {
+        SetExceptionMessage(exception, 'Array is not rectangular - rows have different column counts');
+        ThrowException(exception);
+    }
+    // Validate exact row count constraint if specified
+    if (args?.rows !== undefined && rows !== args.rows) {
+        SetExceptionMessage(exception, `Array has ${rows} rows, expected exactly ${args.rows}`);
+        ThrowException(exception);
+    }
+    // Validate exact column count constraint if specified
+    if (args?.columns !== undefined && columns !== args.columns) {
+        SetExceptionMessage(exception, `Array has ${columns} columns, expected exactly ${args.columns}`);
+        ThrowException(exception);
+    }
+    // Validate minimum row count constraint if specified
+    if (args?.minRows !== undefined && rows < args.minRows) {
+        SetExceptionMessage(exception, `Array has ${rows} rows, minimum required is ${args.minRows}`);
+        ThrowException(exception);
+    }
+    // Validate maximum row count constraint if specified
+    if (args?.maxRows !== undefined && rows > args.maxRows) {
+        SetExceptionMessage(exception, `Array has ${rows} rows, maximum allowed is ${args.maxRows}`);
+        ThrowException(exception);
+    }
+    // Validate minimum column count constraint if specified
+    if (args?.minColumns !== undefined && columns < args.minColumns) {
+        SetExceptionMessage(exception, `Array has ${columns} columns, minimum required is ${args.minColumns}`);
+        ThrowException(exception);
+    }
+    // Validate maximum column count constraint if specified
+    if (args?.maxColumns !== undefined && columns > args.maxColumns) {
+        SetExceptionMessage(exception, `Array has ${columns} columns, maximum allowed is ${args.maxColumns}`);
+        ThrowException(exception);
+    }
+}
+/**
+ * Asserts that an array is not empty.
+ * @template T The type of array elements.
+ * @param value The array to validate.
+ * @param exception Optional custom exception to throw.
+ * @throws {ArrayError} If the array is empty.
+ */
+export function AssertArrayNotEmpty(value, exception = {}) {
+    // Initialize exception configuration with defaults
+    SetExceptionClass(exception, ArrayError);
+    // First validate that it's an array using the base AssertArray function
+    AssertArray(value, undefined, exception);
+    // Then check if the array is empty
+    if (value.length === 0) {
+        SetExceptionMessage(exception, 'Array should not be empty');
+        ThrowException(exception);
+    }
+}
+/**
+ * Asserts that all elements in an array satisfy a predicate.
+ * @template T The type of array elements.
+ * @param array The array to validate.
+ * @param predicate A function to test each element.
+ * @param exception Optional custom exception to throw.
+ * @throws {ArrayError} If any element fails the predicate test.
+ */
+export function AssertArrayAll(array, predicate, exception = {}) {
+    // Initialize exception configuration with defaults
+    SetExceptionClass(exception, ArrayError);
+    // Validate that the value is an array
+    if (!Array.isArray(array)) {
+        SetExceptionMessage(exception, 'Value is not an array');
+        ThrowException(exception);
+    }
+    // Check if all elements satisfy the predicate
+    if (!array.every(predicate)) {
+        SetExceptionMessage(exception, 'Not all elements satisfy the predicate condition');
+        ThrowException(exception);
+    }
+}
+/**
+ * Asserts that at least one element in an array satisfies a predicate.
+ * @template T The type of array elements.
+ * @param array The array to validate.
+ * @param predicate A function to test each element.
+ * @param exception Optional custom exception to throw.
+ * @throws {ArrayError} If no elements pass the predicate test.
+ */
+export function AssertArrayAny(array, predicate, exception = {}) {
+    // Initialize exception configuration with defaults
+    SetExceptionClass(exception, ArrayError);
+    // Validate that the value is an array
+    if (!Array.isArray(array)) {
+        SetExceptionMessage(exception, 'Value is not an array');
+        ThrowException(exception);
+    }
+    // Check if any elements satisfy the predicate
+    if (!array.some(predicate)) {
+        SetExceptionMessage(exception, 'No elements satisfy the predicate condition');
+        ThrowException(exception);
+    }
+}
+//# sourceMappingURL=assert.js.map

package/build/array/assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../../src/array/assert.ts"],"names":[],"mappings":"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"}

package/build/array/index.d.ts

@@ -24,4 +24,5 @@ export * from './array-count-by.js';
 export * from './array-sample.js';
 export type * from './array-element.js';
 export type { TPredicate, TTransform, TComparator, TEqualityComparator } from './types.js';
+export * from './assert.js';
 //# sourceMappingURL=index.d.ts.map

package/build/array/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,mBAAmB,oBAAoB,CAAC;AACxC,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,mBAAmB,oBAAoB,CAAC;AACxC,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC3F,cAAc,aAAa,CAAC"}

package/build/array/index.js

@@ -22,4 +22,5 @@ export * from './array-range.js';
 export * from './array-sort-by.js';
 export * from './array-count-by.js';
 export * from './array-sample.js';
+export * from './assert.js';
 //# sourceMappingURL=index.js.map

package/build/array/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,aAAa,CAAC"}

package/build/array/unique.d.ts

@@ -1,8 +1,18 @@
 /**
  * Returns a new array with duplicate values removed.
- * @param array The input array.
- * @returns A new array with unique values.
- * @note Uses reference equality for objects. Two distinct objects with identical property values are NOT deduplicated.
+ *
+ * @template T - The type of array elements
+ * @param array - The input array
+ * @returns A new array containing only unique values (preserves first occurrence order)
+ *
+ * @remarks Uses reference equality for objects. Two distinct objects with
+ * identical property values are **not** considered equal and will both be kept.
+ *
+ * @example
+ * ```typescript
+ * Unique([1, 2, 2, 3, 1]); // [1, 2, 3]
+ * Unique(['a', 'b', 'a']); // ['a', 'b']
+ * ```
  */
 export declare function Unique<T>(array: T[]): T[];
 //# sourceMappingURL=unique.d.ts.map

package/build/array/unique.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unique.d.ts","sourceRoot":"","sources":["../../src/array/unique.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAMzC"}
+{"version":3,"file":"unique.d.ts","sourceRoot":"","sources":["../../src/array/unique.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAMzC"}

package/build/array/unique.js

@@ -1,8 +1,18 @@
 /**
  * Returns a new array with duplicate values removed.
- * @param array The input array.
- * @returns A new array with unique values.
- * @note Uses reference equality for objects. Two distinct objects with identical property values are NOT deduplicated.
+ *
+ * @template T - The type of array elements
+ * @param array - The input array
+ * @returns A new array containing only unique values (preserves first occurrence order)
+ *
+ * @remarks Uses reference equality for objects. Two distinct objects with
+ * identical property values are **not** considered equal and will both be kept.
+ *
+ * @example
+ * ```typescript
+ * Unique([1, 2, 2, 3, 1]); // [1, 2, 3]
+ * Unique(['a', 'b', 'a']); // ['a', 'b']
+ * ```
  */
 export function Unique(array) {
     if (!array) {

package/build/array/unique.js.map

@@ -1 +1 @@
-{"version":3,"file":"unique.js","sourceRoot":"","sources":["../../src/array/unique.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAI,KAAU;IACnC,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;IACX,CAAC;IAED,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"unique.js","sourceRoot":"","sources":["../../src/array/unique.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,MAAM,CAAI,KAAU;IACnC,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;IACX,CAAC;IAED,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5B,CAAC"}

package/build/asserts/errors.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Base error class for all custom errors in the assertion library.
+ *
+ * Extends the built-in `Error` with a machine-readable `Code` string and an
+ * optional `Context` bag for structured diagnostic metadata. All other error
+ * classes in this module extend `BaseError`.
+ *
+ * @example
+ * ```typescript
+ * class MyError extends BaseError {
+ *   constructor(message: string) {
+ *     super(message, 'MY_ERROR');
+ *   }
+ * }
+ * throw new MyError('Something went wrong');
+ * ```
+ */
+export declare class BaseError extends Error {
+    readonly Code: string;
+    readonly Context: Record<string, unknown> | undefined;
+    /**
+     * @param message - Human-readable description of the error
+     * @param code - Machine-readable error code (e.g. `'VALIDATION_ERROR'`)
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when input data fails a validation rule.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Email address is not valid', { field: 'email' });
+ * ```
+ */
+export declare class ValidationError extends BaseError {
+    /**
+     * @param message - Description of the validation failure
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a runtime type assertion fails.
+ *
+ * @example
+ * ```typescript
+ * throw new AssertionError('Expected string but received number');
+ * ```
+ */
+export declare class AssertionError extends BaseError {
+    /**
+     * @param message - Description of the failed assertion
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a function argument is invalid.
+ * The error message is auto-formatted as
+ * `"Invalid argument '<argumentName>': <reason>"`.
+ *
+ * @example
+ * ```typescript
+ * throw new InvalidArgumentError('userId', 'must be a positive integer');
+ * // message: "Invalid argument 'userId': must be a positive integer"
+ * ```
+ */
+export declare class InvalidArgumentError extends BaseError {
+    /**
+     * @param argumentName - Name of the invalid argument
+     * @param reason - Explanation of why the argument is invalid
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(argumentName: string, reason: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a requested operation is not supported in the current context.
+ * The error message is auto-formatted as `"Operation not supported: <operation>"`.
+ *
+ * @example
+ * ```typescript
+ * throw new NotSupportedError('bulk delete in read-only mode');
+ * // message: "Operation not supported: bulk delete in read-only mode"
+ * ```
+ */
+export declare class NotSupportedError extends BaseError {
+    /**
+     * @param operation - Description of the unsupported operation
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(operation: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a required resource or value cannot be found.
+ * The error message is auto-formatted as `"Not found: <item>"`.
+ *
+ * @example
+ * ```typescript
+ * throw new NotFoundError('user with id 42');
+ * // message: "Not found: user with id 42"
+ * ```
+ */
+export declare class NotFoundError extends BaseError {
+    /**
+     * @param item - Description of the resource that was not found
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(item: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a buffer or collection exceeds its maximum capacity.
+ * The error message is auto-formatted as
+ * `"Buffer overflow: maximum size <maxSize> exceeded"`.
+ *
+ * @example
+ * ```typescript
+ * throw new BufferOverflowError(1000);
+ * // message: "Buffer overflow: maximum size 1000 exceeded"
+ * ```
+ */
+export declare class BufferOverflowError extends BaseError {
+    /**
+     * @param maxSize - The maximum capacity that was exceeded
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(maxSize: number, context?: Record<string, unknown>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/build/asserts/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/asserts/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAU,SAAQ,KAAK;IACnC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAE7D;;;;OAIG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAS5E;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC7C;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9D;AAED;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC5C;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9D;AAED;;;;;;;;;;GAUG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD;;;;OAIG;gBACS,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGnF;AAED;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C;;;OAGG;gBACS,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGhE;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC3C;;;OAGG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG3D;AAED;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9D"}

package/build/asserts/errors.js

@@ -0,0 +1,149 @@
+/**
+ * Base error class for all custom errors in the assertion library.
+ *
+ * Extends the built-in `Error` with a machine-readable `Code` string and an
+ * optional `Context` bag for structured diagnostic metadata. All other error
+ * classes in this module extend `BaseError`.
+ *
+ * @example
+ * ```typescript
+ * class MyError extends BaseError {
+ *   constructor(message: string) {
+ *     super(message, 'MY_ERROR');
+ *   }
+ * }
+ * throw new MyError('Something went wrong');
+ * ```
+ */
+export class BaseError extends Error {
+    Code;
+    Context;
+    /**
+     * @param message - Human-readable description of the error
+     * @param code - Machine-readable error code (e.g. `'VALIDATION_ERROR'`)
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(message, code, context) {
+        super(message);
+        this.name = this.constructor.name;
+        this.Code = code;
+        this.Context = context;
+        if (typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Error thrown when input data fails a validation rule.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Email address is not valid', { field: 'email' });
+ * ```
+ */
+export class ValidationError extends BaseError {
+    /**
+     * @param message - Description of the validation failure
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(message, context) {
+        super(message, 'VALIDATION_ERROR', context);
+    }
+}
+/**
+ * Error thrown when a runtime type assertion fails.
+ *
+ * @example
+ * ```typescript
+ * throw new AssertionError('Expected string but received number');
+ * ```
+ */
+export class AssertionError extends BaseError {
+    /**
+     * @param message - Description of the failed assertion
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(message, context) {
+        super(message, 'ASSERTION_ERROR', context);
+    }
+}
+/**
+ * Error thrown when a function argument is invalid.
+ * The error message is auto-formatted as
+ * `"Invalid argument '<argumentName>': <reason>"`.
+ *
+ * @example
+ * ```typescript
+ * throw new InvalidArgumentError('userId', 'must be a positive integer');
+ * // message: "Invalid argument 'userId': must be a positive integer"
+ * ```
+ */
+export class InvalidArgumentError extends BaseError {
+    /**
+     * @param argumentName - Name of the invalid argument
+     * @param reason - Explanation of why the argument is invalid
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(argumentName, reason, context) {
+        super(`Invalid argument '${argumentName}': ${reason}`, 'INVALID_ARGUMENT', context);
+    }
+}
+/**
+ * Error thrown when a requested operation is not supported in the current context.
+ * The error message is auto-formatted as `"Operation not supported: <operation>"`.
+ *
+ * @example
+ * ```typescript
+ * throw new NotSupportedError('bulk delete in read-only mode');
+ * // message: "Operation not supported: bulk delete in read-only mode"
+ * ```
+ */
+export class NotSupportedError extends BaseError {
+    /**
+     * @param operation - Description of the unsupported operation
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(operation, context) {
+        super(`Operation not supported: ${operation}`, 'NOT_SUPPORTED', context);
+    }
+}
+/**
+ * Error thrown when a required resource or value cannot be found.
+ * The error message is auto-formatted as `"Not found: <item>"`.
+ *
+ * @example
+ * ```typescript
+ * throw new NotFoundError('user with id 42');
+ * // message: "Not found: user with id 42"
+ * ```
+ */
+export class NotFoundError extends BaseError {
+    /**
+     * @param item - Description of the resource that was not found
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(item, context) {
+        super(`Not found: ${item}`, 'NOT_FOUND', context);
+    }
+}
+/**
+ * Error thrown when a buffer or collection exceeds its maximum capacity.
+ * The error message is auto-formatted as
+ * `"Buffer overflow: maximum size <maxSize> exceeded"`.
+ *
+ * @example
+ * ```typescript
+ * throw new BufferOverflowError(1000);
+ * // message: "Buffer overflow: maximum size 1000 exceeded"
+ * ```
+ */
+export class BufferOverflowError extends BaseError {
+    /**
+     * @param maxSize - The maximum capacity that was exceeded
+     * @param context - Optional structured metadata for diagnostics
+     */
+    constructor(maxSize, context) {
+        super(`Buffer overflow: maximum size ${maxSize} exceeded`, 'BUFFER_OVERFLOW', context);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/build/asserts/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/asserts/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IACnB,IAAI,CAAS;IAEb,OAAO,CAAsC;IAE7D;;;;OAIG;IACH,YAAY,OAAe,EAAE,IAAY,EAAE,OAAiC;QAC3E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,OAAO,KAAK,CAAC,iBAAiB,KAAK,UAAU,EAAE,CAAC;YACnD,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACjD,CAAC;IACF,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC7C;;;OAGG;IACH,YAAY,OAAe,EAAE,OAAiC;QAC7D,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,cAAe,SAAQ,SAAS;IAC5C;;;OAGG;IACH,YAAY,OAAe,EAAE,OAAiC;QAC7D,KAAK,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;CACD;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,oBAAqB,SAAQ,SAAS;IAClD;;;;OAIG;IACH,YAAY,YAAoB,EAAE,MAAc,EAAE,OAAiC;QAClF,KAAK,CAAC,qBAAqB,YAAY,MAAM,MAAM,EAAE,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;IACrF,CAAC;CACD;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,iBAAkB,SAAQ,SAAS;IAC/C;;;OAGG;IACH,YAAY,SAAiB,EAAE,OAAiC;QAC/D,KAAK,CAAC,4BAA4B,SAAS,EAAE,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;CACD;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC3C;;;OAGG;IACH,YAAY,IAAY,EAAE,OAAiC;QAC1D,KAAK,CAAC,cAAc,IAAI,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;CACD;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IACjD;;;OAGG;IACH,YAAY,OAAe,EAAE,OAAiC;QAC7D,KAAK,CAAC,iCAAiC,OAAO,WAAW,EAAE,iBAAiB,EAAE,OAAO,CAAC,CAAC;IACxF,CAAC;CACD"}