🎒 Mochila

Your Lightweight Travel Companion for TypeScript Programming

79+ composable TypeScript utilities using a data-last curried pattern for seamless function composition.

Documentation • GitHub • Contributing

Table of Contents

• Philosophy
• Quick Start
• Key Features
• Utilities Overview
• Advanced Examples
• Installation
• Resources

Philosophy

At the core of Mochila's philosophy is the commitment to a "data last" approach in writing functions. This design choice enables easy composition of functions using our internal pipe utility.

Additionally, Mochila embraces currying when necessary, allowing functions to be conveniently partially applied. This flexibility enhances the overall usability of the toolkit.

Benefits:

• ✅ Composable: Chain operations naturally with pipe() and flow()
• ✅ Reusable: Partial application for configurable function factories
• ✅ Type-Safe: Full generic support with proper type inference
• ✅ Chainable: Works seamlessly with function composition patterns

import { length, multiply, pipe } from 'mochila-ts';

const doubleLength = pipe(length, multiply(2));

doubleLength([1, 2, 3]); // 6
doubleLength('abc'); // 6

Quick Start

import { pipe, filter, map, sort, ascending } from 'mochila-ts';

// Compose utilities into a processing pipeline
const processNumbers = pipe(
  filter((x: number) => x > 0),
  map((x: number) => x * 2),
  sort(ascending)
);

processNumbers([-2, 1, 3, -1, 2]); // [2, 4, 6]

// Partial application for reuse
const filterEven = filter((x: number) => x % 2 === 0);
filterEven([1, 2, 3, 4]); // [2, 4]

Key Features

🎯 Type-Safe Composition

• Full TypeScript support with 95%+ type coverage
• Type guards with type narrowing (isArray, isString, etc.)
• Generic constraints maintain type safety in composition chains

⚡ Advanced Utilities

• LRUCache: Configurable caching with TTL and max size
• Debounce/Throttle: Function rate-limiting utilities
• Deep Equality: Circular reference protection with WeakMap
• Array Operations: 34+ array manipulation utilities
• Object/String Manipulation: Pick, omit, split, replace, and more

🔧 Function Utilities

• pipe(): Compose functions with full type inference (up to 9 overloads)
• flow(): Function composition in reverse order
• protect(): Safe function execution
• debounce() & throttle(): Rate-limiting decorators

import { LRUCache } from 'mochila-ts';

const cache = LRUCache({
  max: 100,
  ttl: 1000 * 60 * 60 * 24, // 24 hours
});

cache.set('key', 'value');
cache.get('key'); // 'value'

Utilities Overview

79+ utilities organized by category:

| Category | Count | Examples | |----------|-------|----------| | Array | 34 | append, at, chunkify +31 more | | String | 10 | capitalize, endsWith, join +7 more | | Object | 7 | keys, mapObject, omit +4 more | | Function | 9 | complement, constant, debounce +6 more | | Utility | 7 | castArray, clone, deepClone +4 more | | Logic | 3 | every, none, some | | Number | 4 | add, clamp, divide +1 more | | Assertion | 3 | assert, deepEqual, equal | | Type Guard | 1 | is |

All utilities follow the data-last curried pattern for maximum composability. See the full API documentation for detailed usage.

Advanced Examples

Complex Data Transformation Pipeline

import { pipe, filter, map, groupBy, mapObject, sort, descending } from 'mochila-ts';

interface User {
  id: number;
  name: string;
  age: number;
  active: boolean;
}

const processUsers = pipe(
  filter((u: User) => u.active),
  map((u: User) => ({ ...u, ageGroup: Math.floor(u.age / 10) * 10 })),
  groupBy((u: User & { ageGroup: number }) => u.ageGroup),
  mapObject((users: (User & { ageGroup: number })[]) => users.length)
);

const users = [
  { id: 1, name: 'Alice', age: 28, active: true },
  { id: 2, name: 'Bob', age: 35, active: false },
  { id: 3, name: 'Charlie', age: 22, active: true },
];

processUsers(users); // { '20': 1, '30': 1 }

Type-Safe Type Guards in Action

import { pipe, filter, map } from 'mochila-ts';
import { isString, isNumber } from 'mochila-ts';

const data: unknown[] = [1, 'hello', 2, 'world', null];

const processStrings = pipe(
  filter(isString), // Narrows type to string[]
  map((s: string) => s.toUpperCase()) // ✓ Type-safe
);

processStrings(data); // ['HELLO', 'WORLD']

Caching with TTL

import { pipe, map, LRUCache } from 'mochila-ts';

const expensiveComputation = (n: number) => n * n;

const cache = LRUCache({
  max: 50,
  ttl: 5000, // 5 second TTL
});

const cachedCompute = (n: number) => {
  const cached = cache.get(String(n));
  if (cached !== undefined) return cached;

  const result = expensiveComputation(n);
  cache.set(String(n), result);
  return result;
};

// First call: computes
cachedCompute(5); // 25

// Second call: returns from cache
cachedCompute(5); // 25 (cached)

Installation

Requirements:

• Node.js 20+
• pnpm 9+

npm install mochila-ts
# or
yarn add mochila-ts
# or
pnpm add mochila-ts

All utilities are exposed as named exports:

import { pipe, filter, map } from 'mochila-ts';

Resources

• API Documentation - Complete API reference with examples
• Development Guide - Architecture and contribution guidelines
• GitHub Repository - Source code and issue tracker
• NPM Package - Installation and package info

Made with ❤️ for TypeScript developers who value composition and type safety.