๐ Think your data and let Chaca create it.
## ๐ Intro
Welcome to Chaca, a powerful library that revolutionizes mock data generation for testing and development. Define the shape of your data once and let Chaca generate realistic, diverse and **relational** fake data to simulate any scenario for your application.
Chaca is **isomorphic**: the same API runs in **Node.js and in the browser** (React, Vue, Svelte, ...). Your bundler automatically picks the right build, so you can generate data on the server, in a script, in the CLI, or straight in the browser.
## โจ Features
- ๐ **Runs everywhere** โ Node.js and the browser, ESM and CommonJS, with TypeScript types included.
- ๐งฉ **Batteries included** โ a large set of data `modules` (person, address, internet, finance, image, date, ...) ready to use.
- ๐ **Relational data** โ model references between schemas with `Dataset` and `chaca.ref(...)`.
- ๐ค **Multi-format export** โ serialize to `json`, `csv`, `yaml`, `postgresql`, `java`, `python`, `typescript` and `javascript`.
- ๐ง **Dynamic fields** โ each field can depend on the other fields of the document or on the dataset state.
- ๐น๏ธ **CLI** included to generate data from a config file.
## ๐ฆ Installation
```shell
npm install chaca
```
Requires Node.js >= 18 (when used on the server). In the browser, just import it โ no configuration needed.
## ๐ Usage
### Define a schema and generate data
```ts
import { chaca, modules } from "chaca";
const movieSchema = chaca.schema({
id: chaca.key(() => modules.id.uuid()),
authors: {
type: () => modules.person.fullName({ language: "es" }),
isArray: { min: 1, max: 3 },
},
image: () => modules.image.film(),
likes: () => modules.datatype.int({ min: 0, max: 500000 }),
category: chaca.enum(["Horror", "War", "History", "Comedy"]),
adultMovie: ({ currentFields: docFields }) => {
return docFields.category === "Horror" || docFields.category === "War";
},
});
// Generate 20 objects with the defined schema
const docs = await movieSchema.array(20);
/*
[
{
id: "4136cd0b-d90b-4af7-b485-5d1ded8db252",
authors: ["Olivia Gonzalez Gomez", "Santiago Torres Gil"],
image: "https://loremflickr.com/480/480/film",
likes: 21456,
category: "Horror",
adultMovie: true,
},
...rest, // 19 more documents
];
*/
```
### Serialize in memory โ `transform()` (works in the browser)
`transform` returns the serialized files **in memory** (`{ filename, content }[]`), without touching the filesystem. This is the way to obtain the data in the browser, e.g. to trigger a download.
```ts
const files = await movieSchema.transform(20, {
filename: "movies",
format: "json",
});
// files[0].filename -> "movies.json"
// files[0].content -> "[ { ... }, ... ]" (string, ready to download or display)
```
### Export to files โ `export()` (Node.js only)
`export` writes the generated data to disk.
```ts
await movieSchema.export(20, {
filename: "movies",
format: "json",
location: "./folder",
});
```
> In the browser `export` is not available (there is no filesystem) and throws a descriptive error. Use `transform` instead.
## ๐ Relational data
Use `Dataset` to generate several related schemas at once, referencing fields across them with `chaca.ref("Schema.field")`.
```ts
import { chaca, modules } from "chaca";
const userSchema = chaca.schema({
id: chaca.key(() => modules.id.uuid()),
username: () => modules.internet.username(),
});
const postSchema = chaca.schema({
id: chaca.key(() => modules.id.uuid()),
title: () => modules.lorem.words(),
user: chaca.ref("User.id"), // references a User.id value
});
const dataset = chaca.dataset([
{ name: "User", schema: userSchema, documents: 3 },
{ name: "Post", schema: postSchema, documents: 10 },
]);
const data = await dataset.generate(); // { User: [...], Post: [...] }
// Datasets can be serialized too:
const files = await dataset.transform({ filename: "blog", format: "postgresql" });
```
## ๐งฉ Data modules
Chaca ships with a batteries-included set of data generators, accessible through `modules`:
```ts
modules.person.fullName();
modules.internet.email();
modules.address.country();
modules.finance.bitcoinAddress();
modules.image.film();
modules.datatype.int({ min: 0, max: 100 });
```
See the full list in the [modules documentation](https://chaca.app).
## ๐ค Export formats
Both `transform` and `export` support these `format` values:
`json` ยท `csv` ยท `yaml` ยท `postgresql` ยท `java` ยท `python` ยท `typescript` ยท `javascript`
## ๐ Documentation
Visit our website to read the documentation. [Chaca Docs](https://chaca.app)
## ๐น๏ธ CLI
See [CLI guide](https://chaca.app/docs/guides/cli)
## ๐ Try our REST API
If you don't want to use our npm package you can use our [REST API](https://chaca.app/docs/rest-api/overview) to create your mock data
## ๐๏ธ Changelog
Detailed changes for each release are documented in the [CHANGELOG.md](https://github.com/hgomezrobaina/chaca/blob/main/CHANGELOG.md).
## Contributing
The Chaca project welcomes all constructive contributions. Contributions take many forms, from code for bug fixes and enhancements, to additions and fixes to documentation, additional tests, triaging incoming pull requests and issues, and more!. [See CONTRIBUTING.md](https://github.com/hgomezrobaina/chaca/blob/main/CONTRIBUTING.md)
## License
MIT