✨ Features

• 🐾 Fast fake data generation
• 🐾 Fully written in TypeScript
• 🐾 Simple and expressive API
• 🐾 Extensible and customizable
• 🐾 ESM + CJS support
• 🐾 Multi-locale (e.g., en_US, pt_BR)

📦 Installation

# npm (recommended lowercase scope)
npm install @catniplabs/mango

# or pnpm
pnpm add @catniplabs/mango

🚀 Usage

Functional API (tree-shakeable)

import { fullName, email, pt_BR, en_US } from "@catniplabs/mango";
import { Random } from "@catniplabs/mango/core/random";

const rng = new Random(42); // seed for reproducibility

console.log(fullName(rng, pt_BR)); // e.g., "Laura Oliveira"
console.log(email(rng, en_US));    // e.g., "[email protected]"

Class-based API

import { Mango, pt_BR } from "@catniplabs/mango";

const mango = new Mango({ seed: 1337, locale: pt_BR });

console.log(mango.person.fullName()); // e.g., "Ana Souza"
console.log(mango.internet.email());  // e.g., "[email protected]"

🌐 Browser (CDN)

You can use Mango directly in the browser via jsDelivr or unpkg. Since browsers don't resolve bare specifiers by default, either import by full URL to the ESM file or set up an import map.

Option A — Direct URL (no import map)

Using jsDelivr:

<script type="module">
  import { Mango, pt_BR, en_US } from "https://cdn.jsdelivr.net/npm/@catniplabs/[email protected]/dist/index.mjs";

  const mango = new Mango({ seed: 1337, locale: pt_BR, fallbackLocale: en_US });
  console.log(mango.person.fullName());
  console.log(mango.internet.email());
  console.log(mango.address.full());
</script>

Using unpkg:

<script type="module">
  import { Mango, pt_BR, en_US } from "https://unpkg.com/@catniplabs/mango@latest/dist/index.mjs";

  const mango = new Mango({ seed: 2025, locale: en_US, fallbackLocale: pt_BR });
  console.log(mango.commerce.productName());
  console.log(mango.phone.phone());
</script>

Option B — Import map (use package name in imports)

<script type="importmap">
{
  "imports": {
    "@catniplabs/mango": "https://cdn.jsdelivr.net/npm/@catniplabs/[email protected]/dist/index.mjs"
  }
}
</script>
<script type="module">
  import { Mango, pt_BR } from "@catniplabs/mango";
  const mango = new Mango({ seed: 42, locale: pt_BR });
  document.body.innerText = mango.internet.email();
</script>

Notes:

• The CDN serves ESM with proper CORS headers, so it works in <script type="module">.
• We publish ESM (.mjs) and CJS (.cjs); for browsers, prefer the ESM URL.
• For deterministic results in the browser, use the Mango class’ seed option.

🔌 Plugin support

Mango provides a simple, strongly typed plugin system. Define a plugin with definePlugin, register it via mango.use(plugin) or fetch its API directly with mango.plugin(plugin) (auto-installs if needed).

Define and use a plugin (TypeScript)

import { definePlugin, Mango, pt_BR, en_US } from "@catniplabs/mango";
import type { Locale } from "@catniplabs/mango";

// Create a plugin exposing a typed API
const greetPlugin = definePlugin({
  name: "greet",
  install(ctx) {
    return {
      hello: () => `Hello from ${ctx.getLocale().address.states[0]?.code ?? "--"}`,
      reseed: (seed: number) => ctx.rng.seed(seed),
      setLocale: (locale: Locale) => ctx.setLocale(locale),
    };
  },
});

const mango = new Mango({ seed: 42, locale: pt_BR, fallbackLocale: en_US });

// Get the plugin API with full types (auto-installs if necessary)
const greet = mango.plugin(greetPlugin);
console.log(greet.hello());

// Alternative: register then retrieve
mango.use(greetPlugin);
const greetApi = mango.plugin(greetPlugin);
greetApi.reseed(1337);
greetApi.setLocale(en_US);

Useful public types:

• MangoPlugin<TApi> and PluginContext for strongly typed plugins
• LocaleDefinition to author custom locales/providers

Notes:

• mango.plugin(plugin) is idempotent and preserves the plugin API instance
• getLocale() returns the effective locale with fallback applied

🧩 Scripts

These scripts are available in package.json:

# Development (watch mode)
pnpm dev

# Build (ESM + CJS + types)
pnpm build

# Type checking
pnpm typecheck

# Tests (CI mode) and watch mode
pnpm test
pnpm test:watch

# Lint and auto-fix (Biome)
pnpm lint
pnpm lint:fix

# Format code (Biome)
pnpm format

# Changesets (versioning & publish)
pnpm changeset

# Pre-publish check
pnpm prepublishOnly

# Prepare husky hooks
pnpm prepare

🗺️ Roadmap

Prioritized to deliver a lightweight, realistic, extensible, and multi-environment library.

🎯 MVP (v0.1.x)

• [x] Core RNG with seed (reproducibility)
• [x] ESM + CJS + types (.d.ts) via tsup
• [x] Functional API (tree-shakeable) + optional class (Mango)
• [x] Initial locales: en_US, pt_BR
• [x] Basic generators: person (first/last/fullName), internet.email
• [x] Unit tests with vitest + V8 coverage
• [x] Lint/format with Biome
• [x] CI (build, typecheck, lint, test)

🔸 v0.2.x — Realism and coverage

• [x] Full address (street, number, city, state, ZIP/CEP per locale format)
• [x] phone (valid regional formats)
• [x] date (ranges and practical utilities)
• [x] commerce (product, price, category)
• [x] helpers.multiple / generateMany for batch generation
• [x] Configurable locale fallback (e.g., pt_BR → en_US)

🔶 v0.3.x — Extensibility and DX

• [x] Plugin system (register third-party modules)
• [x] Public types for LocaleDefinition and custom providers

🟠 v0.4.x — Quality and performance

• [ ] Benchmarks (Node and browser) and comparisons
• [ ] Optional lazy-import for locales (on-demand loading)
• [ ] Extended documentation with real-world examples and guides

🟧 v0.5.x — Data reliability

• [ ] Regional validations (e.g., ZIP/CEP, phone formats)
• [ ] Realistic correlations (area code matching city/state, etc.)
• [ ] Dataset reviewed with community contributions

🟩 v1.0.0 — Stable

• [ ] Frozen and documented API
• [ ] Documentation site with playground
• [ ] Migration guide (if needed)
• [ ] Versioning and support policy

📜 License

MIT License

Copyright (c) 2025 CatnipLabs

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.