Skip to main content

lib/zod

Extended Zod schema library with FiveM handle type support.

This module re-exports the standard Zod library with additional schema factories for FiveM's typed handle system. Handles in FiveM are opaque number types that represent game entities, cameras, blips, etc.

Why This Module Exists​

FiveM uses branded number types (e.g., HEntity, HPed, HVehicle) to provide compile-time type safety for entity handles. This module provides Zod schemas that properly parse and transform numbers into these typed handles for use in event payloads and data validation.

Usage​

import { z } from "@core/zod";
 
// Standard Zod types work as expected
const playerDataSchema = z.object({
    name: z.string(),
    health: z.number(),
});
 
// Use FiveM handle schemas for typed handles
const entityEventSchema = z.object({
    entity: z.hentity(),     // HEntity handle
    ped: z.hped(),           // HPed handle
    vehicle: z.hvehicle(),   // HVehicle handle
});
 
// Parse validates and transforms to the correct handle type
const parsed = entityEventSchema.parse({ entity: 12345, ped: 67890, vehicle: 11111 });
// parsed.entity is typed as HEntity
// parsed.ped is typed as HPed
// parsed.vehicle is typed as HVehicle

Available Handle Schemas​

  • z.handle() - Generic Handle
  • z.hentity() - HEntity (any entity)
  • z.hobj() - HObj (world objects)
  • z.hped() - HPed (peds/NPCs)
  • z.hvehicle() - HVehicle (vehicles)
  • z.hcam() - HCam (cameras)
  • z.hpickup() - HPickup (pickups)
  • z.hplayer() - HPlayer (players)
  • z.hscript() - HScript (script handles)
  • z.hblip() - HBlip (map blips)
  • z.hinterior() - HInterior (interiors)
  • z.hfireId() - HFireId (fire instances)

Variables​

z​

const z: {
  handle: () => ZodPipe<ZodNumber, ZodTransform<Handle, number>>;
  hblip: () => ZodPipe<ZodNumber, ZodTransform<HBlip, number>>;
  hcam: () => ZodPipe<ZodNumber, ZodTransform<HCam, number>>;
  hentity: () => ZodPipe<ZodNumber, ZodTransform<HEntity, number>>;
  hfireId: () => ZodPipe<ZodNumber, ZodTransform<HFireId, number>>;
  hinterior: () => ZodPipe<ZodNumber, ZodTransform<HInterior, number>>;
  hobj: () => ZodPipe<ZodNumber, ZodTransform<HObj, number>>;
  hped: () => ZodPipe<ZodNumber, ZodTransform<HPed, number>>;
  hpickup: () => ZodPipe<ZodNumber, ZodTransform<HPickup, number>>;
  hplayer: () => ZodPipe<ZodNumber, ZodTransform<HPlayer, number>>;
  hscript: () => ZodPipe<ZodNumber, ZodTransform<HScript, number>>;
  hvehicle: () => ZodPipe<ZodNumber, ZodTransform<HVehicle, number>>;
};

Defined in: src/lib/zod.ts:127

Type Declaration​

NameTypeDescriptionDefined in
handle()() => ZodPipe<ZodNumber, ZodTransform<Handle, number>>A Zod schema for a handle.src/lib/zod.ts:129
hblip()() => ZodPipe<ZodNumber, ZodTransform<HBlip, number>>A Zod schema for a blip handle.src/lib/zod.ts:138
hcam()() => ZodPipe<ZodNumber, ZodTransform<HCam, number>>A Zod schema for a camera handle.src/lib/zod.ts:134
hentity()() => ZodPipe<ZodNumber, ZodTransform<HEntity, number>>A Zod schema for an entity handle.src/lib/zod.ts:130
hfireId()() => ZodPipe<ZodNumber, ZodTransform<HFireId, number>>A Zod schema for a fire id handle.src/lib/zod.ts:140
hinterior()() => ZodPipe<ZodNumber, ZodTransform<HInterior, number>>A Zod schema for an interior handle.src/lib/zod.ts:139
hobj()() => ZodPipe<ZodNumber, ZodTransform<HObj, number>>A Zod schema for an object handle.src/lib/zod.ts:131
hped()() => ZodPipe<ZodNumber, ZodTransform<HPed, number>>A Zod schema for a ped handle.src/lib/zod.ts:132
hpickup()() => ZodPipe<ZodNumber, ZodTransform<HPickup, number>>A Zod schema for a pickup handle.src/lib/zod.ts:135
hplayer()() => ZodPipe<ZodNumber, ZodTransform<HPlayer, number>>A Zod schema for a player handle.src/lib/zod.ts:136
hscript()() => ZodPipe<ZodNumber, ZodTransform<HScript, number>>A Zod schema for a script handle.src/lib/zod.ts:137
hvehicle()() => ZodPipe<ZodNumber, ZodTransform<HVehicle, number>>A Zod schema for a vehicle handle.src/lib/zod.ts:133