vgpu/coreAdvanced2 symbolsView source ↗

Symbols in this topic

ValidationErrortypeVGPUErrortype

VGPUError

VGPUError is the structured error base class used by vgpu. Use it when you need stable machine-readable code, severity, optional fix, where, and cause fields instead of parsing error messages.

Import

TypeScript
1
import { VGPUError, ValidationError } from "vgpu/core";

Signature

TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
type VGPUErrorSeverity = "error" | "warning" | "info";
 
interface VGPUErrorData {
  readonly code: string;
  readonly message: string;
  readonly severity?: VGPUErrorSeverity;
  readonly fix?: string;
  readonly where?: string;
  readonly cause?: unknown;
}
 
declare class VGPUError extends Error {
  readonly code: string;
  readonly severity: VGPUErrorSeverity;
  readonly fix?: string;
  readonly where?: string;
  readonly cause?: unknown;
  constructor(data: VGPUErrorData);
}
 
declare class ValidationError extends VGPUError {
  constructor(data: Omit<VGPUErrorData, "severity">);
}

Parameters

new VGPUError(data)

ParamTypeRequiredDefaultNotes
data.codestring✔—Stable machine-readable code. Core validation sites use VGPU-CORE-* codes.
data.messagestring✔—Human-readable message passed to Error.
data.severity"error" | "warning" | "info"✖"error"Stored as .severity; omitted data becomes an error.
data.fixstring✖undefinedOptional remediation text.
data.wherestring✖undefinedOptional source/context label such as "Device.createBuffer".
data.causeunknown✖undefinedForwarded to Error via { cause } and stored as .cause.

new ValidationError(data)

ParamTypeRequiredDefaultNotes
data.codestring✔—Stable machine-readable validation code.
data.messagestring✔—Human-readable validation message.
data.fixstring✖undefinedOptional remediation text.
data.wherestring✖undefinedOptional source/context label.
data.causeunknown✖undefinedOptional original error or validation detail.

Returns:

  • new VGPUError(data) returns an Error instance with .name === "VGPUError", .code, .severity, optional .fix, optional .where, and optional .cause.
  • new ValidationError(data) returns a VGPUError subclass with .name === "ValidationError" and .severity === "error".

Throws: Constructors do not throw vgpu errors. They can only throw if the JavaScript runtime cannot construct Error or assign fields.

Examples

TypeScript
1
2
3
4
5
6
7
8
9
10
11
import { VGPUError } from "vgpu/core";
 
const error = new VGPUError({
  code: "VGPU-CORE-INVALID-USAGE",
  message: "Buffer size must be greater than zero.",
  severity: "error",
  where: "Device.createBuffer",
  fix: "Pass a positive byte length.",
});
 
console.log(error.name, error.code, error.severity, error.where);
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import { ValidationError } from "vgpu/core";
 
function requirePositive(value: number): void {
  if (value <= 0) {
    throw new ValidationError({
      code: "VGPU-CORE-INVALID-USAGE",
      message: "Expected a positive value.",
      where: "example.requirePositive",
    });
  }
}
 
try {
  requirePositive(0);
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.code); // "VGPU-CORE-INVALID-USAGE"
  }
}
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { createMockAdapter } from "vgpu/mock";
import { VGPUError } from "vgpu/core";
 
const device = await createMockAdapter().requestDevice();
 
device.pushErrorScope("validation");
device.createBuffer({ size: 0, usage: ["copy_dst"] });
const error = await device.popErrorScope();
 
if (error instanceof VGPUError) {
  console.log(error.code); // "VGPU-CORE-INVALID-USAGE"
}
 
device.destroy();

Notes

  • Match on .code, not .message. Messages can become more descriptive; codes are the stable contract.
  • ValidationError forces severity to "error"; use VGPUError directly for "warning" or "info" severities.
  • Core currently emits these VGPU-CORE-* codes from core layer (vgpu/core) code paths: VGPU-CORE-INVALID-USAGE, VGPU-CORE-VALIDATION, VGPU-CORE-EXTERNAL-TEXTURE, VGPU-CORE-TEXTURE-RESIZE-LOCKED, VGPU-CORE-TEXTURE-DESTROYED, VGPU-CORE-UNSUPPORTED-FORMAT, VGPU-CORE-BIND-GROUP-LAYOUT-REQUIRED, VGPU-CORE-SAMPLER-ANISOTROPY-FILTERS, VGPU-CORE-BINDING-INVALID, and VGPU-CORE-VISIBILITY-INVALID.
  • Native WebGPU errors are converted to VGPU-CORE-VALIDATION only by Device.popErrorScope(); other native calls may still throw native errors directly.
  • See also: Device, Buffer, Texture, bind, VGPUAdapter.