@gtcx/validators

Validation utilities and structured error types for the GTCX protocol stack.

Installation

pnpm add @gtcx/validators

API

GtcxError

Structured error class with machine-readable code and optional details.

import { GtcxError } from '@gtcx/validators';

throw new GtcxError('INVALID_ARGUMENT', 'jurisdiction is required', { field: 'jurisdiction' });

Error codes: INVALID_ARGUMENT, NOT_FOUND, UNAUTHORIZED, INTERNAL, SCHEMA_VALIDATION_FAILED, REPLAY_DETECTED, SIGNATURE_INVALID, STATE_TRANSITION_INVALID, EXPIRED, VERSION_CONFLICT, RATE_LIMITED.

invalidArg(message, details?) / notImplemented(message, details?)

Factory functions for common error types.

Assertion helpers

import {
  assertNonEmptyString,
  assertFiniteNumber,
  assertPositiveNumber,
  assertInRange,
  assertArrayNotEmpty,
  assertFutureTimestamp,
  assertValidDid,
  assertValidJurisdiction,
} from '@gtcx/validators';

assertNonEmptyString(value, 'operatorId'); // throws if empty/non-string
assertInRange(score, 0, 100, 'gciScore'); // throws if out of bounds
assertValidDid(did, 'issuer'); // validates did:gtcx:<method>_<id>
assertValidJurisdiction(code, 'jurisdiction'); // validates 2-6 uppercase alphanum

isValidDid(value) / isNonEmptyString(value)

Non-throwing boolean validators.

GTCX_DID_PATTERN

Canonical DID regex: ^did:gtcx:[a-z]{2,6}_[a-zA-Z0-9_]{1,64}$

Testing

pnpm vitest run packages/validators/

License

BSL 1.1 -- converts to Apache 2.0 on January 1, 2030.