const userAssertion: ObjectAssertion = {
name: assertString,
address: addressAssertion, // nested object
};
`

#### Cross-Field Validation

`typescript
const userAssertion: ObjectAssertion = {
name: assertString,
age: assertNumber,
email: assertEmail,
$o: user => {
// Custom validation after all fields pass
assertTruthy(user.age >= 18, 'User must be 18 or older');
},
};
`

#### Strict Mode (No Extra Fields)

`typescript
assertObject(
{ name: 'Alice', age: 30, unknownField: 'oops' },
userAssertion,
undefined,
{ failOnUnknownFields: true }, // ✗ throws: "property can't be checked: unknownField"
);
`

$3

#### Basic Arrays

`typescript
import { assertArray, arrayAssertion } from '@fishka/assertions';

assertArray(['a', 'b', 'c'], assertString); // ✓
assertArray([1, 2, 3], assertNumber); // ✓

// Or create reusable array assertion
const stringArrayAssertion = arrayAssertion(assertString);
assertArray(['x', 'y'], stringArrayAssertion);
`

#### Array Constraints

`typescript
// Length constraints
assertArray([1, 2, 3], assertNumber, { minLength: 2, maxLength: 5 }); // ✓
assertArray([1], assertNumber, { minLength: 2 }); // ✗ throws

// Uniqueness check
assertArray(
['a', 'b', 'c'],
assertString,
{ uniqueByIdentity: v => v }, // ✓
);

assertArray(
['a', 'a', 'b'],
assertString,
{ uniqueByIdentity: v => v }, // ✗ throws: "array contains non-unique elements"
);
`

#### Arrays in Objects

`typescript
import { undefinedOr } from '@fishka/assertions';

interface User {
name: string;
tags?: string[];
}

const userAssertion: ObjectAssertion = {
name: assertString,
tags: undefinedOr(arrayAssertion(assertString)),
};
`

$3

`typescript
import { assertRecord, recordAssertion } from '@fishka/assertions';

// Record
assertRecord({ a: 1, b: 2, c: 3 }, assertNumber); // ✓

// With key validation
assertRecord(
{ 'user@example.com': 'Alice' },
assertString,
{ keyAssertion: assertEmail }, // validates keys are emails
);

// Ensure key matches field in value
assertRecord(
{
user123: { id: 'user123', name: 'Alice' },
user456: { id: 'user456', name: 'Bob' },
},
objectAssertion({ id: assertString, name: assertString }),
{ keyField: 'id' }, // ensures record key === value.id
);
`

$3

#### Type-checked Custom Assertions

`typescript
import { $a } from '@fishka/assertions';

// Create custom assertion with type checking
const assertPositive = $a(value => value > 0, 'Must be positive');

assertPositive(42); // ✓
assertPositive(-5); // ✗ throws: "Check is failed: Must be positive"
`

#### Untyped Custom Assertions

`typescript
import { $u } from '@fishka/assertions';

const assertValidDate = $u(value => value instanceof Date && !isNaN(value.getTime()), 'Must be a valid Date');

assertValidDate(new Date()); // ✓
assertValidDate(new Date('invalid')); // ✗ throws
`

#### String Constraints

`typescript
import { stringAssertion } from '@fishka/assertions';

const passwordAssertion = stringAssertion({
minLength: 8,
maxLength: 64,
});

passwordAssertion('short'); // ✗ throws: "length is too small: 5 < 8"
passwordAssertion('validpassword'); // ✓
`

$3

`typescript
import { validateObject } from '@fishka/assertions';

function handleFormSubmit(formData: unknown) {
const error = validateObject(formData, userAssertion);

if (error) {
// Show error to user
console.error('Validation failed:', error);
return { success: false, error };
}

// formData is now typed as User
saveUser(formData);
return { success: true };
}
`

$3

#### Option 1: API Request Validation (Express.js Server)

Validate incoming HTTP requests on the server side:

`typescript
import express from 'express';
import { validateObject, assertObject, type ObjectAssertion } from '@fishka/assertions';

interface CreateUserRequest {
name: string;
email: string;
age: number;
tags?: string[];
}

const createUserRequestAssertion: ObjectAssertion = {
name: assertString,
email: assertEmail,
age: assertNumber,
tags: undefinedOr(arrayAssertion(assertString)),
};

const app = express();
app.use(express.json());

// POST /users - Create new user
app.post('/users', (req, res) => {
// Validate request body
const error = validateObject(req.body, createUserRequestAssertion);
if (error) {
return res.status(400).json({ success: false, error: Invalid request: ${error} });
}
// req.body is now typed as CreateUserRequest
const user = createUser(req.body);
res.status(201).json({ success: true, data: user });
});

// GET /users/:id - Get user by ID
app.get('/users/:id', (req, res) => {
const userId = req.params.id;
// Validate UUID format
assertUuid(userId, 'userId');
const user = getUserById(userId);
res.json({ success: true, data: user });
});
`

#### Option 2: API Response Validation (Client-side)

Validate API responses on the client to ensure type safety:

`typescript
interface ApiResponse {
success: boolean;
data: T;
error?: string;
}

interface User {
id: string;
name: string;
email: string;
createdAt: string;
}

interface UsersListResponse {
users: User[];
meta: {
total: number;
page: number;
pageSize: number;
};
}

// Define response assertion
const userAssertion: ObjectAssertion = {
id: assertUuid,
name: assertString,
email: assertEmail,
createdAt: assertString,
};

const usersListResponseAssertion: ObjectAssertion = {
users: arrayAssertion(userAssertion),
meta: {
total: assertNumber,
page: assertNumber,
pageSize: assertNumber,
},
};

// Client function to fetch users
async function fetchUsers(page: number = 1): Promise {
const response = await fetch(/api/users?page=${page});
const data: unknown = await response.json();

// Validate response structure
assertObject(data, usersListResponseAssertion);

// Now data is fully typed as UsersListResponse!
return data;
}

// Usage
const { users, meta } = await fetchUsers(1);
console.log(Loaded ${users.length} of ${meta.total} users);
`

#### Bonus: Middleware Pattern for Express

Create reusable validation middleware:

`typescript
import { Request, Response, NextFunction } from 'express';
import { validateObject, type ObjectAssertion } from '@fishka/assertions';

// Generic validation middleware
function validateBody(assertion: ObjectAssertion) {
return (req: Request, res: Response, next: NextFunction) => {
const error = validateObject(req.body, assertion);

if (error) {
return res.status(400).json({
success: false,
error: Validation failed: ${error},
});
}

// Body is valid, continue to route handler
next();
};
}

// Use the middleware
app.post('/users', validateBody(createUserRequestAssertion), (req, res) => {
// req.body is typed and validated
const user = createUser(req.body);
res.status(201).json({ success: true, data: user });
});
`

API Reference

$3

`typescript
assertString(value: unknown, context?: string): asserts value is string
assertNumber(value: unknown, context?: string): asserts value is number
assertBoolean(value: unknown, context?: string): asserts value is boolean
assertDate(value: unknown, context?: string): asserts value is Date
assertNonNullable(value: T, context?: string): asserts value is NonNullable
`

$3

`typescript
assertUuid(value: unknown, context?: string): asserts value is string
assertHexString(value: unknown, context?: string): asserts value is string
assertEmail(value: unknown, context?: string): asserts value is string
`

$3

`typescript
assertObject(
value: unknown,
assertion: ObjectAssertion,
context?: string,
constraints?: { failOnUnknownFields?: boolean; allowedUnknownFieldNames?: string[] }
): asserts value is T

assertArray(
value: unknown,
elementAssertion: Assertion,
constraints?: { minLength?: number; maxLength?: number; uniqueByIdentity?: (el: T) => string },
context?: string
): asserts value is Array

assertRecord(
value: unknown,
valueAssertion: Assertion,
constraints?: { keyAssertion?: (key: string) => void; keyField?: string },
context?: string
): asserts value is Record
`

$3

`typescript
arrayAssertion(elementAssertion: Assertion, constraints?): ValueAssertion>
recordAssertion(valueAssertion: Assertion, constraints?): ValueAssertion>
objectAssertion(objAssertion: ObjectAssertion): ValueAssertion

$a(checkFn: (value: T) => boolean, errorMsg?: string): ValueAssertion
$u(checkFn: (value: unknown) => boolean, errorMsg?: string): ValueAssertion

undefinedOr(assertion: Assertion): Assertion
nullOr(assertion: Assertion): Assertion
valueOr(expectedValue: T, orAssertion: Assertion): Assertion

stringAssertion(constraints: { minLength?: number; maxLength?: number }): ValueAssertion
`

$3

`typescript
validateObject(value: unknown, assertion: ObjectAssertion, context?, constraints?): string | undefined
validateArray(value: unknown, elementAssertion: Assertion, constraints?, context?): string | undefined
validateRecord(value: unknown, valueAssertion: Assertion, constraints?, context?): string | undefined
`

$3

`typescript
isString(value: unknown): value is string
isNumber(value: unknown): value is number
isBoolean(value: unknown): value is boolean
isDate(value: unknown): value is Date
isUuid(value: unknown): value is string
isHexString(value: unknown): value is string
isEmail(value: unknown, constraints?): value is string
isNonNullable(value: T): value is NonNullable
`

$3

`typescript
assertTruthy(value: unknown, error?: string | (() => string)): asserts value
fail(error?: string | (() => string)): never // throws assertion error
`

Advanced Features

$3

Errors automatically include the full path to the failing field:

`typescript
const data = {
user: {
profile: {
age: 'twenty', // wrong type
},
},
};

assertObject(data, userAssertion, 'apiResponse');
// throws: "apiResponse.user.profile.age: Not a number "
`

$3

ObjectAssertion is compile-time verified - TypeScript ensures all fields are covered:

`typescript
interface User {
name: string;
age: number;
email: string;
}

const userAssertion: ObjectAssertion = {
name: assertString,
age: assertNumber,
// ✗ TypeScript error: Property 'email' is missing
};
`

$3

Override the default error factory for all assertions:

`typescript
import { setDefaultAssertionErrorFactory } from '@fishka/assertions';

setDefaultAssertionErrorFactory((message: string) => {
return new CustomError(message);
});
`

Common Patterns

$3

`typescript
interface AppConfig {
port: number;
host: string;
database: {
url: string;
poolSize: number;
};
features: string[];
}

const configAssertion: ObjectAssertion = {
port: assertNumber,
host: assertString,
database: {
url: assertString,
poolSize: assertNumber,
},
features: arrayAssertion(assertString),
};

const config: unknown = JSON.parse(configFileContents);
assertObject(config, configAssertion);
// config is now fully typed and validated
`

$3

`typescript
function validateLoginForm(formData: FormData): { error?: string; data?: LoginData } {
const input = {
email: formData.get('email'),
password: formData.get('password'),
};

const error = validateObject(input, loginAssertion);
if (error) {
return { error };
}

return { data: input };
}
`

$3

`typescript
function processValue(value: unknown) {
if (isString(value)) {
// TypeScript knows value is string
console.log(value.toUpperCase());
} else if (isNumber(value)) {
// TypeScript knows value is number
console.log(value.toFixed(2));
}
}
``

Why @fishka/assertions?

- Type Safety: Leverages TypeScript's type system for compile-time and runtime safety
- Developer Experience: Clear error messages with full context path
- Zero Dependencies: No external dependencies, minimal bundle size
- Flexible: Choose between throwing assertions or returning error messages
- Composable: Build complex validators from simple building blocks
- Battle-tested: Comprehensive test suite with 111+ tests

License

MIT

Contributing

Issues and pull requests are welcome at https://gitea.com/fishka/assertions