Samech

A precise and reliable TypeScript validation library with a modular API.

Samech is a schema validation and parsing library built for TypeScript. It focuses on precision, reliability, and modularity, taking inspiration from libraries like Valibot.

Why Samech?

With mature options like Zod or Valibot already existing, why build another validation library?

• Learning & Understanding: I firmly believe that the best way to understand how a tool works under the hood is to build one yourself. Samech is born from a deep curiosity to explore how type validation and parsing libraries are constructed from scratch.
• Zero Bloat Philosophy: I dislike libraries that do more than they should. While tools like Zod and Valibot are excellent and not inherently bloated, building my own allows me to strictly limit the scope to exactly what is necessary and nothing else.
• Tailored Developer Experience: Creating this library gives me the freedom to design an API that perfectly adapts to my personal style and preferences.

Features

• Modular API: Import only what you need, keeping your bundle sizes extremely small.
• Type-safe: Excellent TypeScript support. Infer your input and output types directly from your schemas.
• Sync & Async: Built-in support for both synchronous and asynchronous validations.
• Developer Experience: Simple, intuitive, and predictable API.

Quick Start

Here is a quick example of the modular API approach:

import * as s from "samech";

// 1. Define your schema
const UserSchema = s.object({
  id: s.number(),
  username: s.string(),
  email: s.string()
});

// 2. Infer TypeScript types automatically
type UserInput = s.Input<typeof UserSchema>;
type UserOutput = s.Output<typeof UserSchema>;

// 3. Parse and validate your data
const data = {
  id: 1,
  username: "samech",
  email: "[email protected]"
};

const result = s.parse(UserSchema, data);

API Reference

Samech provides a comprehensive and modular set of schemas, validators, transformers, and utilities.

Methods

• parse / parseAsync: Parses data and throws a SamechParseError on failure.
• safeParse / safeParseAsync: Parses data safely, returning a success/error result object instead of throwing.
• standard: Adapter for the Standard Schema specification.

Schemas

• Primitives: any(), bigint(), boolean(), date(), enum(), literal(), nan(), never(), null(), number(), string(), symbol(), undefined(), unknown(), void()
• Structural: array(), intersection(), map(), object(), record(), set(), tuple(), union()
• Utility: brand(), catch(), custom(), enhance(), fallback(), lazy(), nullable(), nullish(), optional(), pipe()

Actions (Validators & Transformers)

Use actions alongside the pipe utility to validate or transform your data during parsing.

• String Validators: cuid(), email(), emoji(), endsWith(), includes(), ip(), lowerCase(), mac(), regex(), startsWith(), upperCase(), url(), uuid()
• String Transformers: capitalize(), normalize(), toLowerCase(), toUpperCase(), trim()
• Number Validators: integer(), multipleOf(), negative(), nonnegative(), nonpositive(), positive(), safeInteger()
• Number Transformers: abs(), ceil(), clamp(), floor(), round()
• Length & Value Validators: length(), maxLength(), minLength(), nonempty(), max(), min()
• Custom Actions: check(), refine(), transform()

Core Types

• Schema<TInput, TOutput>: The base interface for synchronous schemas.
• AsyncSchema<TInput, TOutput>: The base interface for asynchronous schemas.
• GenericSchema<TInput, TOutput>: A union type representing either a synchronous or an asynchronous schema.

Utility Types

• Input<TSchema>: Utility type to extract the input type from a given schema.
• Output<TSchema>: Utility type to extract the output type from a given schema.

License

MIT - Built with ❤️ by Sergio Casado