About SmooAI

SmooAI is an AI-powered platform for helping businesses multiply their customer, employee, and developer experience.

Learn more on smoo.ai

SmooAI Packages

Check out other SmooAI packages at npmjs.com/org/smooai

About @smooai/utils

The foundation that eliminates boilerplate - Battle-tested utilities that handle the repetitive tasks so you can focus on building features, not infrastructure.

Why @smooai/utils?

Ever found yourself writing the same error handler for the 50th time? Debugging Lambda functions without proper request tracking? Wrestling with phone number validation that works everywhere except production? You're not alone.

We built @smooai/utils because we were tired of:

• 🔁 Copy-pasting the same utility functions across projects
• 🐛 Inconsistent error handling breaking production deploys
• 🔍 Losing request context across AWS services
• 📱 Phone numbers failing validation in different formats
• 🗺️ HTTP headers losing their case-sensitivity battles
• 🎯 Writing custom validators for every data type

Now, with one package, you get:

• ✅ Production-tested utilities used across all SmooAI services
• ✅ Type-safe implementations with full TypeScript support
• ✅ AWS Lambda integration that just works
• ✅ Human-readable error messages your team will thank you for
• ✅ Zero configuration needed - sensible defaults out of the box

Install

pnpm add @smooai/utils

Real-World Solutions

🚀 Lambda Error Handling That Actually Works

Stop writing try-catch blocks in every Lambda function. Our battle-tested apiHandler does it all:

import { apiHandler } from '@smooai/utils';

// Before: Boilerplate everywhere
export const handler = async (event, context) => {
    try {
        // Parse body
        // Validate input
        // Handle errors
        // Format response
        // Log everything
    } catch (error) {
        // More error handling
    }
};

// After: Focus on your logic
export const handler = apiHandler(async (event, context) => {
    const user = await createUser(event.body);
    return { statusCode: 201, body: user };
});
// Automatic error handling, logging, and response formatting ✨

🎯 Validation With Human-Readable Errors

Your users (and your support team) deserve better than "ValidationError at path[0].nested.field":

import { handleSchemaValidation, HumanReadableSchemaError } from '@smooai/utils';

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

try {
    const user = handleSchemaValidation(userSchema, data);
    // user.phone is guaranteed to be E.164 format: +12125551234
} catch (error) {
    if (error instanceof HumanReadableSchemaError) {
        console.log(error.humanReadableMessage);
        // "Email must be a valid email address. Phone must be a valid phone number. Age must be at least 18."
    }
}

🔍 Case-Insensitive Collections for HTTP Headers

Because Content-Type, content-type, and CONTENT-TYPE should all just work:

import { CaseInsensitiveMap } from '@smooai/utils';

const headers = new CaseInsensitiveMap([
    ['Content-Type', 'application/json'],
    ['X-API-KEY', 'secret'],
]);

headers.get('content-type'); // 'application/json' ✅
headers.has('X-Api-Key'); // true ✅
headers.get('CONTENT-TYPE'); // 'application/json' ✅

🏭 Production-Ready Hono Apps for Lambda

Set up a fully-configured API with one line:

import { createAwsLambdaHonoApp } from '@smooai/utils';

const app = createAwsLambdaHonoApp();

app.get('/health', (c) => c.json({ status: 'healthy' }));

app.post('/users', async (c) => {
    // Automatic request ID tracking
    // Built-in error handling
    // Pretty JSON in development
    const user = await createUser(await c.req.json());
    return c.json(user, 201);
});

export const handler = handle(app);

📁 Smart File Discovery

Find configuration files without hardcoding paths:

import { findFile } from '@smooai/utils';

// Searches up the directory tree until it finds the file
const configPath = await findFile('smoo.config.json');
const packageJson = await findFile('package.json');

// Perfect for:
// - Finding project root
// - Loading environment-specific configs
// - Locating test fixtures

🌍 Environment Detection Made Simple

import { isRunningInProd, isRunningLocally } from '@smooai/utils';

if (isRunningLocally()) {
    // Enable debug logging
    // Use local database
    // Show detailed errors
}

if (isRunningInProd()) {
    // Use production services
    // Enable monitoring
    // Sanitize error messages
}

More Powerful Examples

🛡️ Type-Safe Error Handling

Transform cryptic errors into actionable messages:

import { ApiError, errorHandler } from '@smooai/utils';

const processPayment = errorHandler(
    async (orderId: string) => {
        // Throws ApiError with 404 status
        if (!order) throw new ApiError('Order not found', 404);

        // Validation errors become 400s with details
        const validated = handleSchemaValidation(schema, data);

        // Unexpected errors are logged and sanitized
        return await chargeCard(order);
    },
    {
        logger: console,
        onError: (error) => notifyOps(error),
    },
);

⏱️ Smart Async Utilities

import { sleep } from '@smooai/utils';

// Rate limiting made easy
for (const batch of batches) {
    await processBatch(batch);
    await sleep(1000); // Wait 1 second between batches
}

// Retry with exponential backoff
async function retryWithBackoff(fn, attempts = 3) {
    for (let i = 0; i < attempts; i++) {
        try {
            return await fn();
        } catch (error) {
            if (i === attempts - 1) throw error;
            await sleep(Math.pow(2, i) * 1000);
        }
    }
}

📞 Phone Number Validation That Works Globally

import { validateAndTransformPhoneNumber } from '@smooai/utils';

// Accepts multiple formats, outputs E.164
const phoneSchema = z.object({
    phone: validateAndTransformPhoneNumber,
});

phoneSchema.parse({ phone: '(212) 555-1234' });
// ✅ { phone: '+12125551234' }

phoneSchema.parse({ phone: '+44 20 7946 0958' });
// ✅ { phone: '+442079460958' }

phoneSchema.parse({ phone: '555-1234' });
// ❌ Throws: "Phone must be a valid phone number"

Built for Production

Every utility in this package is:

• 🔒 Type-safe - Full TypeScript support with strict types
• ⚡ Performance tested - Optimized for real-world usage
• 📊 Battle-tested - Used in production at SmooAI
• 📚 Well-documented - Clear examples and use cases
• 🔄 Maintained - Regular updates and improvements

Testing

pnpm test

Linting

pnpm lint

Contributing

We're currently developing our contribution processes. If you're interested in contributing to this package or have questions, please reach out to us through the contact information below.

Contact

Brent Rager

• Email
• LinkedIn
• BlueSky
• TikTok
• Instagram

Smoo Github: https://github.com/SmooAI