@makroz/core

Part of the MK-Director suite — Platform-agnostic types, design tokens, and utility functions. Zero dependencies. Works in browser, React Native, and Node.js environments.

🔧 Installation

pnpm add @makroz/core
# or
npm install @makroz/core

📦 Features Overview

1. Types & Interfaces

Core type definitions used to ensure type-safety across Web and Mobile applications:

• MkResponse<T>: Standardized API response envelope.
• ListParams: Interface for search, sort, and pagination query params.
• MkUser: Base user definition with abilities parsing support.
• MkFormField / MkFormFields: Form field rule definitions.
• MkCrudConfig / MkCrudReturn: Configuration and return values for automatic CRUD hooks.
• MkToast / MkToastOptions: Types for the notifications system.

2. Design Tokens (tokens)

System-level style tokens for both light and dark themes, plus shared values (radius, fonts). Used by @makroz/web and @makroz/mobile to guarantee visual parity:

• Colors: primary, primaryForeground, background, foreground, muted, border, error, success, warning, info.
• Shared: radius (default: 8px), fontSans (default: 'Inter').

3. Permission Checker (canUser)

Utility to check if a user has access to a resource based on a pipe-delimited abilities string. Actions must be a known friendly name (add/edit/delete/view) or a raw code (C/U/D/R); unknown actions return false (deny-by-default — no typo bypass).

import { canUser } from '@makroz/core';

const abilities = 'posts:CRUD|users:R|reports:CR';
canUser(abilities, 'posts', 'edit');   // true
canUser(abilities, 'users', 'delete'); // false
canUser(abilities, 'users', 'X');      // false (unknown action, deny-by-default)
canUser('**', 'any', 'add');           // true (Super Admin wildcard)

🔧 Utility Modules

mkDates

Locale-aware date formatting with GMT offset configuration:

import { mkDates } from '@makroz/core';

mkDates.configure({ gmtOffset: -4, locale: 'es' });

mkDates.format('2026-04-15T12:00:00Z');        // "15/04/2026"
mkDates.formatDateTime('2026-04-15T12:00:00Z'); // "Mar, 15 abril - 08:00"
mkDates.timeAgo('2026-04-15T12:00:00Z');        // "Hace 3 días"
mkDates.ranges.thisMonth();                     // { from: '2026-04-01', to: '2026-04-30' }

mkNumbers

Number and currency formatting:

import { mkNumbers } from '@makroz/core';

mkNumbers.configure({ locale: 'es', currencySymbol: '$' });

mkNumbers.currency(1500);       // "$ 1.500,00"
mkNumbers.compact(1500000);     // "1.5M"
mkNumbers.percent(0.856);       // "85,60%"
mkNumbers.clamp(150, 0, 100);   // 100

mkStrings

Common string manipulation helpers:

import { mkStrings } from '@makroz/core';

mkStrings.initials('Mario Guzman');    // "MG"
mkStrings.slug('Hello World!');        // "hello-world"
mkStrings.truncate('Very long text', 8); // "Very lon..."
mkStrings.mask('1234567890', 4);       // "******7890"

mkArrays

Helpers to manipulate arrays and collections:

import { mkArrays } from '@makroz/core';

mkArrays.groupBy(users, 'role');       // { admin: [...], member: [...] }
mkArrays.unique([1, 2, 2, 3]);         // [1, 2, 3]
mkArrays.sum(products, 'price');       // total sum
mkArrays.sample([1, 2, 3, 4]);         // random element

mkValidation

Declarative form validation engine:

import { mkValidation } from '@makroz/core';

const rules = {
    name: { required: true, rules: ['required', 'min:3'], api: 'ae', label: 'Nombre' },
    email: { required: true, rules: ['required', 'email'], api: 'ae', label: 'Email' }
};

// Validate form
const errors = mkValidation.checkFields(rules, formData, 'add');
// Returns e.g. { name: 'Mínimo 3 caracteres' }

// Validate single value
const error = mkValidation.check('', ['required']); // 'Este campo es requerido'

// Extract payload for API
const payload = mkValidation.getApiFields(formData, rules, 'add');

mkPhone

Parsing and formatting telephone numbers:

import { mkPhone } from '@makroz/core';

mkPhone.parse('+591 70012345'); // { countryCode: '591', nationalNumber: '70012345', isValid: true }
mkPhone.whatsappLink('70012345', 'Hola!'); // "https://wa.me/59170012345?text=Hola!"

mkFunctions

Pure function utilities:

import { mkFunctions } from '@makroz/core';

const debounced = mkFunctions.debounce(saveData, 300);
const throttled = mkFunctions.throttle(trackScroll, 100);
await mkFunctions.delay(1000); // 1-second promise delay

mkFiles

Helpers for size formatting, base64 operations, and extensions:

import { mkFiles } from '@makroz/core';

mkFiles.formatFileSize(1536000);   // "1.46 MB"
mkFiles.getExt('document.pdf');    // "pdf"
mkFiles.isImage('photo.png');      // true
mkFiles.base64ToBlob('SGVsbG8=');  // Blob

mkI18n

Lightweight translations engine with dotted key navigation and interpolation:

import { mkI18n } from '@makroz/core';

mkI18n.addTranslations('es', { welcome: 'Hola {name}!' });
mkI18n.setLocale('es');
mkI18n.t('welcome', { name: 'Mario' }); // "Hola Mario!"

mkStorage

Unified file upload utility supporting web File and React Native file objects ({ uri, type, name }):

import { mkStorage } from '@makroz/core';

await mkStorage.upload(file, {
    url: 'https://api.cloudinary.com/v1_1/cloud/image/upload',
    additionalData: { upload_preset: 'preset' }
});

🧪 Testing

pnpm test