PipeType

Runtime schemas with TypeScript‑style unions via real |.
PipeType models types as bigint flags. You compose unions with bitwise OR and use those flags inside object schemas that validate at construction time and on every assignment.

⚠️ Experimental Library: PipeType is an experimental project exploring bitwise operations for runtime validation. It is not intended as a replacement for mature libraries like Zod or Valibot. For production applications, we recommend using established validation libraries. This project serves as a proof-of-concept for alternative approaches to runtime type validation.

Quick look

import { Type, string, number, boolean, array, literal, validate } from "pipetype"

// 1) Natural unions with real "|"
const StringOrNumber = string | number
const isStringOrNumber = validate(StringOrNumber)

isStringOrNumber("ok")  // true
isStringOrNumber(42)    // true
isStringOrNumber(true)  // false

// 2) Schemas: validated on create and on each assignment
Type.User = {
  id: string | number,      // union works inside schemas
  name: string,
  email: string,
  isActive: boolean,
}

const user = Type.User({
  id: "u_1",
  name: "Jane",
  email: "[email protected]",
  isActive: true,
})

user.id = 123        // ✓ ok
user.id = false      // ✗ throws ValidationError

// 3) Arrays (element validation) and literals (ad‑hoc enums)
Type.TodoList = {
  title: string,
  items: array(string),
}

Type.Status = {
  value: literal("active") | literal("inactive") | literal("pending"),
  updatedAt: string,
}

Install

npm i pipetype
# or
pnpm add pipetype
# or
yarn add pipetype

Why this exists

Most validators treat unions as a DSL call (z.union([...]), S.union(...)). PipeType treats types as bit masks so A | B is a real union. That keeps declarations short and lets the same primitives power schemas that enforce types both at construction and during writes.

Core API (stable surface)

Primitive type flags

string, number, boolean, bigint, symbol, nil, undef, nullish, any, unknown, never, date

Each is a bigint mask. You can use them directly in unions or inside schemas.

import { string, number, validate } from "pipetype"

const mask = string | number         // 1n | 2n -> 3n
const ok = validate(mask)            // (v: unknown) => boolean

ok("x")   // true
ok(1)     // true
ok(true)  // false

validate(maskOrValidator)

Curried helper that returns a predicate for a mask (or a named validator). Handy for guards and tests.

const isString = validate(string)
if (!isString(maybe)) throw new Error("need a string")

Type — schemas and named validators

• Schemas: assign a plain object of field → type to Type.YourName, then call it as a factory:

  Type.Person = {
    name: string,
    age: number,
    address: {
      street: string,
      city: string,
      zipCode: string | number,
    },
  }
  
  const p = Type.Person({
    name: "Bob",
    age: 30,
    address: { street: "123 Main", city: "NYC", zipCode: 10001 },
  })
  
  p.address.zipCode = "10002"  // ✓
  p.address.zipCode = null     // ✗ throws

• Named validators: you can attach your own predicate functions on Type and use them in schemas:

  Type.email = (v: unknown) => typeof v === "string" && v.includes("@")
  
  Type.Account = {
    id: string,
    email: Type.email,    // field must satisfy your predicate
  }

Note: Custom validators are function predicates. They can be used as field types; unions of primitive masks are the primary composition mechanism.

array(elementType)

Define homogeneous arrays and validate each element on write:

Type.Tags = { tags: array(string) }

const t = Type.Tags({ tags: ["a", "b"] })
t.tags = ["ok", 1]   // ✗ throws (non‑string element)

literal(value)

Create a literal type and combine with | for enum‑like fields:

const Active = literal("active")
const Inactive = literal("inactive")
const Pending = literal("pending")

Type.Job = { status: Active | Inactive | Pending }

Error handling

• Invalid construction or assignment throws a ValidationError with a useful path message.
• Prefer validate(...) when you want a non‑throwing boolean guard.

try {
  user.id = false
} catch (e) {
  console.error(String(e)) // e.g., "ValidationError: $.id expected (string|number) got boolean"
}

Real‑world patterns

Discriminated unions (string literal tags)

const KindA = literal("a")
const KindB = literal("b")

Type.Node = {
  kind: KindA | KindB,
  value: string | number,
}

const n = Type.Node({ kind: "a", value: "x" })
n.kind = "b"     // ✓
n.kind = "oops"  // ✗

Config with flexible IDs

Type.Service = {
  id: string | number,
  name: string,
  enabled: boolean,
}

Nested arrays of objects

Type.List = {
  title: string,
  items: array(Type.Service),
}

Limitations & roadmap

• Intersections (A & B) — not implemented. Intersections require all checks to pass; the bit‑mask model handles unions (ANY) cleanly, but intersections (ALL) need sequential predicate logic. Future work may add function‑based intersections.
• Coercion / parsing — PipeType validates values you give it; it doesn’t coerce. Add your own parsing before construction if needed.
• Schema inference — This is a runtime lib. You still get good DX in TS, but static type inference is intentionally minimal compared to parser‑based libs.

Appendix A — How the bitwise model works

1. Bit allocation — each primitive validator is assigned a unique bit in a bigint (e.g., 1n, 2n, 4n, …).
2. Union via | — composing unions is OR’ing those flags (1n | 2n = 3n).
3. Membership via & — to validate, PipeType maps a runtime value to its primitive flag and checks (flag & mask) !== 0n.
4. Schemas — objects returned by Type.Name(initial) are Proxies; set traps validate new values against each field’s mask (recurse for nested schemas / arrays).
5. Why no intersections — a mask can’t require multiple independent predicates at once; intersections need function composition that runs all checks.

Appendix B — Complete, runnable examples

B1. User + Status

import { Type, string, number, boolean, array, literal, validate } from "pipetype"

Type.Status = {
  value: literal("active") | literal("inactive") | literal("pending"),
  updatedAt: string,
}

Type.User = {
  id: string | number,
  name: string,
  email: string,
  isActive: boolean,
  tags: array(string),
  status: Type.Status,
}

const u = Type.User({
  id: "u1",
  name: "Ada",
  email: "[email protected]",
  isActive: true,
  tags: ["founder"],
  status: { value: "active", updatedAt: new Date().toISOString() },
})

u.tags.push("admin")     // ✓
u.status.value = "bad"   // ✗ throws

B2. Guards with validate()

import { string, number, validate } from "pipetype"

const isStringOrNumber = validate(string | number)

function takesStringOrNumber(x: unknown) {
  if (!isStringOrNumber(x)) throw new Error("bad input")
}

License

MIT