validate API

Schema validation with WASM-accelerated rule evaluation in web workers.

npm install @rowops/validate

---

Worker Factory

createValidatorWorker

Creates a web worker for validation.

import { createValidatorWorker } from "@rowops/validate";

const worker = createValidatorWorker();

worker.postMessage({
  requestId: "1",
  type: "validate",
  payload: {
    ipcBytes: arrowIpcBuffer,
    schema: mySchema,
  },
});

worker.onmessage = (event) => {
  const response = event.data;
  console.log("Valid rows:", response.payload.validCount);
};

---

Worker Protocol

WorkerRequest

Base request type for validation worker messages.

interface WorkerRequest<T = unknown> {
  requestId: string;
  type: string;
  payload: T;
}

ValidateRequest

Request payload for validation.

interface ValidateRequest {
  ipcBytes: Uint8Array;
  schema: RowOpsSchema;
  options?: {
    stopOnFirstError?: boolean;
    batchSize?: number;
  };
}

ValidateResponse

Response from validation worker.

interface ValidateResponse {
  validCount: number;
  invalidCount: number;
  errors: ValidationError[];
  validIpcBytes?: Uint8Array;
  invalidIpcBytes?: Uint8Array;
}

interface ValidationError {
  rowIndex: number;
  field: string;
  code: string;
  message: string;
  value?: unknown;
}

---

Schema Types

RowOpsSchema

Defines the validation schema structure.

interface RowOpsSchema {
  id: string;
  name: string;
  description?: string;
  fields: RowOpsSchemaField[];
  versionId?: string;
  version?: number;
  tier?: "free" | "pro" | "scale" | "enterprise";
}

RowOpsSchemaField

Individual field definition in a schema.

interface RowOpsSchemaField {
  key: string;
  label: string;
  required?: boolean;
  type?: "string" | "number" | "date" | "boolean";
  regex?: string;
  /** Semantic type for built-in pattern validation */
  semanticType?: SemanticType;
  enumValues?: string[];
  transforms?: TransformRule[];
  /** Minimum value for number fields */
  min?: number;
  /** Maximum value for number fields */
  max?: number;
  /** Minimum length for string fields */
  minLength?: number;
  /** Maximum length for string fields */
  maxLength?: number;
}

type SemanticType =
  | "email"
  | "phone"
  | "url"
  | "ssn"
  | "zipcode"
  | "creditcard"
  | "uuid"
  | "ipv4"
  | "ipv6";

type TransformRule = "trim" | "lowercase" | "uppercase";

---

Validation Rules

Built-in Validations

Rule	Description	Example
required	Field must have a non-empty value	{ required: true }
type	Value must match type	{ type: "number" }
regex	Value must match pattern	{ regex: "^[A-Z]{2}$" }
semanticType	Value must match semantic pattern	{ semanticType: "email" }
enumValues	Value must be in allowed list	{ enumValues: ["A", "B"] }
min	Number must be at least value	{ min: 0 }
max	Number must be at most value	{ max: 100 }
minLength	String must have at least N chars	{ minLength: 3 }
maxLength	String must have at most N chars	{ maxLength: 50 }

Semantic Type Validation

Use built-in patterns for common data types:

const schema: RowOpsSchema = {
  id: "users",
  name: "Users",
  fields: [
    { key: "email", label: "Email", required: true, semanticType: "email" },
    { key: "phone", label: "Phone", semanticType: "phone" },
    { key: "website", label: "Website", semanticType: "url" },
    { key: "ssn", label: "SSN", semanticType: "ssn" },
    { key: "zipcode", label: "ZIP Code", semanticType: "zipcode" },
  ],
};

Type Validation

const schema: RowOpsSchema = {
  id: "contacts",
  name: "Contacts",
  fields: [
    { key: "email", label: "Email", type: "string", required: true },
    { key: "age", label: "Age", type: "number" },
    { key: "active", label: "Active", type: "boolean" },
    { key: "created", label: "Created", type: "date" },
  ],
};

Regex Validation

const schema: RowOpsSchema = {
  id: "products",
  name: "Products",
  fields: [
    {
      key: "sku",
      label: "SKU",
      required: true,
      regex: "^[A-Z]{3}-\\d{4}$", // ABC-1234 format
    },
    {
      key: "email",
      label: "Email",
      regex: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
    },
  ],
};

Enum Validation

const schema: RowOpsSchema = {
  id: "employees",
  name: "Employees",
  fields: [
    {
      key: "department",
      label: "Department",
      required: true,
      enumValues: ["Engineering", "Sales", "Marketing", "HR", "Finance"],
    },
    {
      key: "status",
      label: "Status",
      enumValues: ["active", "inactive", "pending"],
    },
  ],
};

Range Validation

const schema: RowOpsSchema = {
  id: "products",
  name: "Products",
  fields: [
    {
      key: "price",
      label: "Price",
      type: "number",
      required: true,
      min: 0,
      max: 10000,
    },
    {
      key: "quantity",
      label: "Quantity",
      type: "number",
      min: 1,
    },
    {
      key: "sku",
      label: "SKU",
      required: true,
      minLength: 5,
      maxLength: 20,
    },
    {
      key: "description",
      label: "Description",
      maxLength: 500,
    },
  ],
};

---

Error Codes

Code	Description
required	Required field is empty or null
type_number	Value cannot be cast to number
type_boolean	Value cannot be cast to boolean
type_date	Value cannot be parsed as date
pattern	Value doesn't match regex pattern
semanticType	Value doesn't match semantic type pattern (email, phone, etc.)
enum	Value not in allowed enum list
min	Number is below minimum value
max	Number exceeds maximum value
minLength	String is shorter than minimum length
maxLength	String exceeds maximum length

---

Usage Example

import { createValidatorWorker } from "@rowops/validate";

async function validateData(arrowIpcBytes: Uint8Array) {
  const worker = createValidatorWorker();

  return new Promise((resolve, reject) => {
    worker.onmessage = (event) => {
      const response = event.data;
      if (response.type === "error") {
        reject(new Error(response.payload.message));
      } else {
        resolve(response.payload);
      }
      worker.terminate();
    };

    worker.onerror = reject;

    worker.postMessage({
      requestId: crypto.randomUUID(),
      type: "validate",
      payload: {
        ipcBytes: arrowIpcBytes,
        schema: {
          id: "my-schema",
          name: "My Schema",
          fields: [
            { key: "name", label: "Name", required: true },
            { key: "email", label: "Email", required: true, regex: "^.+@.+$" },
            { key: "age", label: "Age", type: "number" },
          ],
        },
      },
    });
  });
}

---

Tier Restrictions

Feature	Free	Pro	Scale	Enterprise
Required/type validation	Yes	Yes	Yes	Yes
Regex validation	Yes	Yes	Yes	Yes
Enum validation	Yes	Yes	Yes	Yes
Range validation (min/max)	Yes	Yes	Yes	Yes
Length validation (minLength/maxLength)	Yes	Yes	Yes	Yes
Max rows per validation	1,000	100,000	1,000,000	Unlimited

---

See Also

• Schema Configuration
• Error Codes Reference
• Validation Guide