🛡️ Narrowland

A lightweight TypeScript library providing type guards, type assertions, and invariant utilities for runtime type narrowing.

🚀 30-Second Pitch

Narrowland solves the problem of runtime type narrowing in TypeScript applications. Instead of writing verbose type checks and assertions, you get a clean, consistent API that provides:

• Type Guards (is.*) - Check types without throwing errors, perfect for conditional logic
• Type Assertions (assert.*) - Throw errors for invalid types with full TypeScript inference
• Invariant Utilities (ensure, invariant, raiseError) - Handle edge cases and invariants gracefully

All functions are tree-shakeable, zero-dependency, and fully typed with TypeScript's type narrowing. You can import individual functions or use the grouped APIs.

📦 Installation

npm install narrowland
# or
pnpm add narrowland
# or
yarn add narrowland

🎯 Quick Start

// Import individual functions (tree-shakeable)
import { isString, assertNumber, ensure, invariant } from 'narrowland'

// Or import grouped APIs
import { is, assert, ensure, invariant } from 'narrowland'

// Type guards - return boolean, don't throw
if (isString(userInput)) {
  // userInput is now typed as string
  console.log(userInput.toUpperCase())
}

// Type guards from grouped import
if (is.string(userInput)) {
  // userInput is now typed as string
  console.log(userInput.toUpperCase())
}

// Assertions - throw on invalid types
assertNumber(age) // throws if not a number
// age is now typed as number

// Assertions from grouped import
assert.number(age) // throws if not a number
// age is now typed as number

// Ensure - return value or throw (only for null/undefined)
const name = ensure(user.name, 'Name is required')
// name is typed as NonNullable<typeof user.name>

// Invariant - check conditions (throws on falsy, does nothing on truthy)
invariant(isString(items), 'Items must be a string')

📚 API Reference

All functions except is.* throw errors if the condition is not satisfied.

Type Guards (is.*)

Type guards return boolean and narrow types without throwing errors. Safer than assertions because they don't throw.

Function	Type Guard	Description
is.defined(value)	value is NonNullable<T>	Checks if value is not null or undefined
is.notNull(value)	value is Exclude<T, null>	Checks if value is not null
is.truthy(value)	value is Exclude<T, false | 0 | '' | null | undefined>	Checks if value is truthy
is.falsy(value)	value is Extract<T, false | 0 | '' | null | undefined>	Checks if value is falsy
is.string(value)	value is string	Checks if value is a string
is.nonEmptyString(value)	value is string	Checks if value is a non-empty string
is.number(value)	value is number	Checks if value is a finite number
is.boolean(value)	value is boolean	Checks if value is a boolean
is.bigint(value)	value is bigint	Checks if value is a bigint
is.symbol(value)	value is symbol	Checks if value is a symbol
is.instanceOf(value, constructor)	value is T	Checks if value is an instance of the given constructor
is.array(value)	value is T[]	Checks if value is an array
is.nonEmptyArray(value)	value is [T, ...T[]]	Checks if value is a non-empty array
is.arrayOf(value, guard)	value is T[]	Checks if value is an array whose items satisfy the provided guard
is.stringLiteral(value, literals) ⚠️	value is T[number]	Checks if value is a member of string literals array (deprecated: use is.oneOf instead, will be removed in v2.0.0)
is.oneOf(value, collection)	value is T[number]	Checks if value is a member of the provided collection (works with any type)
is.object(value)	value is T	Checks if value is a plain object
is.propertyOf(key, predicate)	obj is T & { [P in K]-?: U }	Checks that the selected property satisfies the provided predicate and makes it required
is.keyOf(value, record)	value is T & keyof U	Checks if value is a key of the provided record

Type Assertions (assert.*)

Assertions throw errors for invalid types and narrow types in the same scope. Use when you expect the value to be valid.

Function	Assertion	Description
assert.defined(value, message?)	asserts value is NonNullable<T>	Throws if value is null or undefined
assert.notNull(value, message?)	asserts value is Exclude<T, null>	Throws if value is null
assert.truthy(value, message?)	asserts value is Exclude<T, false | 0 | '' | null | undefined>	Throws if value is falsy
assert.falsy(value, message?)	asserts value is Extract<T, false | 0 | '' | null | undefined>	Throws if value is truthy
assert.string(value, message?)	asserts value is string	Throws if value is not a string
assert.nonEmptyString(value, message?)	asserts value is string	Throws if value is not a non-empty string
assert.number(value, message?)	asserts value is number	Throws if value is not a finite number
assert.boolean(value, message?)	asserts value is boolean	Throws if value is not a boolean
assert.bigint(value, message?)	asserts value is bigint	Throws if value is not a bigint
assert.symbol(value, message?)	asserts value is symbol	Throws if value is not a symbol
assert.instanceOf(value, constructor, message?)	asserts value is T	Throws if value is not an instance of the given constructor
assert.array(value, message?)	asserts value is T[]	Throws if value is not an array
assert.nonEmptyArray(value, message?)	asserts value is [T, ...T[]]	Throws if value is not a non-empty array
assert.arrayOf(value, guard, message?)	asserts value is T[]	Throws if value is not an array whose items satisfy the provided guard
assert.stringLiteral(value, literals, message?) ⚠️	value is T[number]	Throws if value is not a member of provided string literals array (deprecated: use assert.oneOf instead, will be removed in v2.0.0)
assert.oneOf(value, collection, message?)	asserts value is T[number]	Throws if value is not a member of the provided collection (works with any type)
assert.object(value, message?)	asserts value is T	Throws if value is not a plain object
assert.keyOf(value, record, message?)	asserts value is T & keyof U	Throws if value is not a key of the provided record
assert.fromPredicate(predicate, message?)	(value, message?) => asserts value is T	Creates custom assertion from predicate

Invariant Utilities

Function	Return Type	Description
ensure<T>(value, message?)	NonNullable<T>	Returns value or throws if null/undefined (only checks nullish)
invariant(condition, message?)	asserts condition	Throws if condition is falsy (generic condition checker)
raiseError(message, options?)	never	Throws error with custom name/code/cause (most flexible)

🎨 When to Use What?

Narrowland provides a palette of solutions from most generic to very specific:

Type Guards (is.*) - Safest, Most Flexible

• Use when: You want to check types without throwing
• Best for: Conditional logic, filtering, optional validation
• Example: if (isString(value)) { /* value is string */ }

Type Assertions (assert.*) - Most Direct

• Use when: You expect the value to be valid and want to fail fast
• Best for: Input validation, API boundaries, when you're confident about the type
• Example: assertString(userInput) - throws immediately if not string

Ensure - Specific Null/Undefined Check

• Use when: You have a maybe value and know it should be defined
• Best for: Optional chaining results, API responses, configuration values
• Throws: If value is null or undefined (similar to invariant, but only for nullish values)
• Example: const name = ensure(user.name) - only checks for null/undefined

Invariant - Generic Condition Checker

• Use when: You want to check any condition, not just types
• Best for: Business logic validation, state checks, complex conditions
• Example: invariant(user.age >= 18, 'User must be adult')

RaiseError - Most Flexible Error Creation

• Use when: You need custom error types with specific properties or inline assertions
• Best for: API errors, domain-specific errors, when you need error codes, inline assertions
• Example: getUserById(maybeId ?? raiseError('User id must be defined'))

🍳 Copy-Paste Recipes

Type Guards - Simple Checks

import { isDefined, isTruthy } from 'narrowland'

// Check if value exists
if (isDefined(maybeValue)) {
  // maybeValue is now NonNullable<typeof maybeValue>
  console.log(maybeValue)
}

// Check if value is truthy
if (isTruthy(userInput)) {
  // userInput is now truthy type
  return userInput
}

Assertions - Fail Fast

import { assertString } from 'narrowland'

function processInput(input: unknown) {
  assertString(input) // throws if not string
  // input is now string
  return input.toUpperCase()
}

Ensure - Handle Null/Undefined

import { ensure } from 'narrowland'

function getUserName(user: { name?: string | null }) {
  // ensure throws if null/undefined, returns value otherwise
  const name = ensure(user.name, 'Name is required')
  // name is now string (was string | null | undefined)
  return name
}

Invariant - Business Rules

import { invariant } from 'narrowland'

function calculateAge(birthYear: number) {
  invariant(birthYear > 1900, 'Invalid birth year')
  invariant(birthYear <= new Date().getFullYear(), 'Birth year cannot be in future')
  
  return new Date().getFullYear() - birthYear
}

Filtering Arrays

import { isString, isInstanceOf } from 'narrowland'

// Filter strings from mixed array
const mixedArray = ['hello', 42, 'world', true]
const strings = mixedArray.filter(isString) // TypeScript knows these are strings

// Filter Date instances from mixed array
const values = [new Date(), '2023-01-01', new Date('2024-01-01'), null, 42]
const dates = values.filter((v) => isInstanceOf(v, Date)) // TypeScript knows `dates` is Date[]

Property Guards - Filter Objects by Required Keys

import { isDefined, isPropertyOf } from 'narrowland'

type User = {
  id: string
  email?: string | null
}

const users: User[] = [
  { id: '1', email: 'one@example.com' },
  { id: '2', email: null },
  { id: '3' },
]

const hasEmail = isPropertyOf('email', isDefined)

const contactableUsers = users.filter(hasEmail)
// ?^ contactableUsers is typed as PropNarrow<User, "email", {}>[]
contactableUsers.forEach((user) => {
  user.email.toLowerCase()
  // ?^ user.email is typed as string
})

ArrayOf - Array Type Narrowing

import { isArrayOf, isString } from 'narrowland'

// Narrow array of strings
const maybeStringArray: unknown = ['hello', 'world', 'typescript']
if (isArrayOf(maybeStringArray, isString)) {
  // maybeStringArray is now typed as string[]
  const uppercased = maybeStringArray.map((s) => s.toUpperCase())
}

OneOf - Union Type Narrowing

import { isOneOf, assertOneOf } from 'narrowland'

// Works with any type, not just strings
const status = 'pending' as unknown
const validStatuses = ['pending', 'completed', 'failed'] as const

// Type guard - returns boolean
if (isOneOf(status, validStatuses)) {
  // status is now typed as 'pending' | 'completed' | 'failed'
  console.log(status.toUpperCase())
}

// Assertion - throws if invalid
assertOneOf(status, validStatuses)
// status is now typed as 'pending' | 'completed' | 'failed'

// Works with mixed types too
const value = 42 as unknown
const allowedValues = [42, 'hello', true, null] as const

if (isOneOf(value, allowedValues)) {
  // value is now typed as 42 | 'hello' | true | null
}

KeyOf - Safe Object Key Access

import { isKeyOf, assertKeyOf } from 'narrowland'

const handlers = {
  click: () => 'clicked',
  submit: () => 'submitted',
} as const

// Type guard - returns boolean
const eventName = 'click' as string
if (isKeyOf(eventName, handlers)) {
  // eventName is now typed as 'click' | 'submit'
  handlers[eventName]() // Safe to call
}

// Assertion - throws if invalid
assertKeyOf(eventName, handlers)
// eventName is now typed as 'click' | 'submit'
handlers[eventName]() // Safe to call

📊 Bundle Size

• Size: 902 B (minified + brotli)
• Dependencies: 0
• Tree-shakeable: ✅ (import individual functions)
• ESM + CJS: ✅

🛠️ Development

Prerequisites

• Node.js 20+
• pnpm 8+

Setup

# Clone the repository
git clone https://github.com/your-username/narrowland.git
cd narrowland

# Install dependencies
pnpm install

# Build the library
pnpm build

# Run in development mode
pnpm dev

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git switch -c feat/amazing-feature)
3. Commit your changes (git commit -m 'feat: add some amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Add tests for new functionality
• Update documentation as needed

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by tiny-invariant for the invariant pattern
• Built with modern tooling: Vitest, Biome, RSLib
• Zero dependencies for maximum compatibility

---

Made with ❤️ for the TypeScript community