Data Validation

Event Tracker provides schema-based data type validation using the Standard Schema specification to ensure the accuracy of event parameters.
With this feature, events are validated against predefined structures before being collected, helping to ensure data reliability, prevent errors, and provide a foundation for structured analytics.

The library supports any schema validation library that implements the Standard Schema specification, including Zod, Valibot, ArkType, and more.

Usage

You can define schemas in two ways: using the Standard Schema interface directly or using any Standard Schema-compatible library like Zod.

Option 1: Standard Schema Interface (Built-in)


import { createTracker } from "@offlegacy/event-tracker";
 
// Helper function to create Standard Schema-compliant schemas
function createSchema<T>(validator: (value: unknown) => T) {
  return {
    "~standard": {
      version: 1,
      vendor: "custom",
      validate: (value: unknown) => {
        try {
          const result = validator(value);
          return { value: result };
        } catch (error) {
          return {
            issues: [{ message: error instanceof Error ? error.message : "Validation failed" }],
          };
        }
      },
    },
  };
}
 
const schemas = {
  page_view: createSchema((value: unknown): { title: string } => {
    if (typeof value?.title !== "string") {
      throw new Error("title must be a string");
    }
    return { title: value.title };
  }),
  click_button: createSchema((value: unknown): { target: string } => {
    if (typeof value?.target !== "string") {
      throw new Error("target must be a string");
    }
    return { target: value.target };
  }),
};
 
const [Track] = createTracker<{}, {}, typeof schemas>({
  schema: {
    schemas,
    onSchemaError: (error) => {
      console.error("Schema validation failed:", error);
    },
    abortOnError: true,
  },
});

Option 2: Using Zod (Standard Schema Compatible)


import { createTracker } from "@offlegacy/event-tracker";
import { z } from "zod";
 
const schemas = {
  page_view: z.object({
    title: z.string(),
  }),
  click_button: z.object({
    target: z.string(),
  }),
};
 
const [Track] = createTracker<{}, {}, typeof schemas>({
  schema: {
    schemas,
    onSchemaError: (error) => {
      console.error("Schema validation failed:", error);
    },
    abortOnError: true,
  },
});

Reference

Option	Type	Description	Default
`schemas`	`Record<string, StandardSchemaV1>`	Mapping of event names to Standard Schema-compliant schemas	Required
`onSchemaError`	`(error: StandardSchemaV1.Issue[]) => void \| Promise<void>`	Function called when schema validation fails	Optional
`abortOnError`	`boolean`	Whether to abort event processing on validation error	`false`

When abortOnError is set to true, events that fail schema validation will not be tracked.

Examples

Define Schemas

Choose either the built-in Standard Schema approach or use an external library:

Option A: Built-in Standard Schema


const schemas = {
  page_view: createSchema((value: unknown): { title: string } => {
    if (typeof value?.title !== "string") {
      throw new Error("title must be a string");
    }
    return { title: value.title };
  }),
  click_button: createSchema((value: unknown): { target: string } => {
    if (typeof value?.target !== "string") {
      throw new Error("target must be a string");
    }
    return { target: value.target };
  }),
};

Option B: Using Zod


import { z } from "zod";
 
const schemas = {
  page_view: z.object({
    title: z.string(),
  }),
  click_button: z.object({
    target: z.string(),
  }),
};

Register with `createTracker`


const [Track] = createTracker<{}, {}, typeof schemas>({
  schema: {
    schemas,
    abortOnError: true,
    onSchemaError: (error) => {
      console.error("Schema validation error:", error);
    },
  },
});

Schema-Based Event Tracking


<Track.PageView schema="page_view" params={{ title: "Home" }} />
<Track.Click schema="click_button" params={{ target: "submit-button" }} />

If schema validation passes, the event is sent to send or the respective handler. If it fails, onSchemaError is triggered, and if abortOnError is true, the event is discarded.

Notes

Standard Schema validation uses the validate method from the schema’s ~standard property
Type inference: For better type safety and IntelliSense, define schemas outside of the createTracker function and pass typeof schemas as the third type argument: createTracker<Context, EventParams, typeof schemas>
Schema validation errors include detailed messages and path information for debugging
All schema approaches (built-in Standard Schema, Zod, Valibot, etc.) provide the same level of type safety when properly configured