@natiwo/core

Core utilities, types, and error handling for TypeScript applications

Installation

pnpm add @natiwo/core
# or
npm install @natiwo/core
# or
yarn add @natiwo/core

Features

• 🎯 Result Pattern - Type-safe error handling without exceptions
• ✅ Validation - Schema validation with Zod integration
• 🛡️ Enhanced Errors - Rich error classes with context
• 🔧 Utilities - 130+ utility functions (strings, arrays, objects, dates)
• 📝 Types - Common TypeScript types and utilities

Quick Start

Result Pattern

import { Result } from '@natiwo/core';

// Wrap async operations
const result = await Result.from(
  fetch('https://api.example.com/users')
);

if (result.isOk()) {
  const data = result.unwrap();
  console.log(data);
} else {
  const error = result.unwrapErr();
  console.error(error);
}

// Chain operations
const processed = await Result.from(getUserById(id))
  .map(user => user.name)
  .mapErr(err => new CustomError('User fetch failed', err));

Validation

import { validate, schemas } from '@natiwo/core';
import { z } from 'zod';

const UserSchema = z.object({
  email: z.string().email(),
  age: z.number().min(18),
});

const result = validate(UserSchema, {
  email: '[email protected]',
  age: 25,
});

if (result.isOk()) {
  const user = result.unwrap(); // Type-safe!
}

Utility Functions

import { sleep, retry, chunk, pick, omit } from '@natiwo/core';

// Async utilities
await sleep(1000);
const data = await retry(() => fetchData(), { retries: 3 });

// Array utilities
const chunks = chunk([1, 2, 3, 4, 5], 2); // [[1,2], [3,4], [5]]

// Object utilities
const subset = pick(user, ['id', 'name']);
const filtered = omit(user, ['password']);

Enhanced Errors

import { 
  ApplicationError, 
  ValidationError, 
  NotFoundError 
} from '@natiwo/core/errors';

throw new NotFoundError('User not found', { userId: '123' });

throw new ValidationError('Invalid email', {
  field: 'email',
  value: 'invalid',
});

API Reference

Result<T, E>

Type-safe wrapper for operations that may fail.

Methods:

• isOk(): boolean - Check if result is successful
• isErr(): boolean - Check if result is error
• unwrap(): T - Get value (throws if error)
• unwrapErr(): E - Get error (throws if ok)
• unwrapOr(defaultValue: T): T - Get value or default
• map<U>(fn: (value: T) => U): Result<U, E> - Transform value
• mapErr<F>(fn: (error: E) => F): Result<T, F> - Transform error

Static Methods:

• Result.ok<T>(value: T) - Create success result
• Result.err<E>(error: E) - Create error result
• Result.from<T>(promise: Promise<T>) - Wrap async operation

Utilities

String:

• capitalize(str) - Capitalize first letter
• slugify(str) - Convert to URL-safe slug
• truncate(str, length) - Truncate with ellipsis
• camelCase(str), snakeCase(str), kebabCase(str) - Case conversion

Array:

• chunk(array, size) - Split into chunks
• unique(array) - Remove duplicates
• groupBy(array, key) - Group by property
• shuffle(array) - Randomize order

Object:

• pick(obj, keys) - Select properties
• omit(obj, keys) - Exclude properties
• deepMerge(obj1, obj2) - Deep merge objects
• isEmpty(obj) - Check if empty

Date:

• formatDate(date, format) - Format date
• addDays(date, days) - Add days
• diffDays(date1, date2) - Difference in days

Async:

• sleep(ms) - Async delay
• retry(fn, options) - Retry with backoff
• timeout(promise, ms) - Add timeout to promise

Validation

import { validate, ValidationError } from '@natiwo/core';

const result = validate(schema, data);
// Returns Result<T, ValidationError>

Brazilian Utilities

import { validateCPF, validateCNPJ, formatCPF } from '@natiwo/core';

const isValid = validateCPF('123.456.789-00');
const formatted = formatCPF('12345678900'); // '123.456.789-00'

TypeScript Types

import type { 
  DeepPartial,
  DeepRequired,
  Prettify,
  Constructor,
  AsyncFunction,
  Nullable
} from '@natiwo/core/types';

type User = {
  id: string;
  profile: {
    name: string;
    email: string;
  };
};

type PartialUser = DeepPartial<User>;
// All properties optional, recursively

Best Practices

1. Always use Result for operations that may fail

   // ❌ Bad
   async function getUser(id: string) {
     return await db.user.findUnique({ where: { id } });
   }
   
   // ✅ Good
   async function getUser(id: string) {
     return await Result.from(
       db.user.findUnique({ where: { id } })
     );
   }

2. Validate user input

   const result = validate(CreateUserSchema, req.body);
   if (result.isErr()) {
     return res.status(400).json({ error: result.unwrapErr() });
   }

3. Use utility functions to avoid reinventing the wheel

   // ❌ Bad
   const names = users.map(u => u.name).filter((n, i, a) => a.indexOf(n) === i);
   
   // ✅ Good
   const names = unique(users.map(u => u.name));

License

MIT © NATIWO Sistemas