npm package: @seedts/faker
Description: Faker.js integration for SeedTS - generate realistic fake data
Author: SeedTS Contributors
Latest version: 0.1.1

# @seedts/faker

Faker.js integration for SeedTS - Generate realistic fake data for database seeding.

## Installation

```bash
npm install @seedts/faker @faker-js/faker
# or
pnpm add @seedts/faker @faker-js/faker
# or
yarn add @seedts/faker @faker-js/faker
```

## Quick Start

```typescript
import { faker } from '@seedts/faker';
import { Seed, Action, Entity, Attribute } from '@seedts/jsx-runtime';

export const UsersSeed = (props) => (
  <Seed name="users" adapter={props.adapter}>
    <Action count={50}>
      <Entity>
        <Attribute name="email" factory={faker.email()} />
        <Attribute name="firstName" factory={faker.firstName()} />
        <Attribute name="lastName" factory={faker.lastName()} />
        <Attribute name="avatar" factory={faker.avatar()} />
        <Attribute name="bio" factory={faker.paragraph()} />
      </Entity>
    </Action>
  </Seed>
);
```

## Pre-built Factories

Use pre-built factories for common data patterns:

```typescript
import { userFactory, postFactory, productFactory } from '@seedts/faker/factories';

// User with all common fields
<Entity>
  <Attribute name="email" factory={userFactory.email} />
  <Attribute name="firstName" factory={userFactory.firstName} />
  <Attribute name="lastName" factory={userFactory.lastName} />
  <Attribute name="username" factory={userFactory.username} />
  <Attribute name="password" factory={userFactory.password} />
  <Attribute name="avatar" factory={userFactory.avatar} />
  <Attribute name="phone" factory={userFactory.phone} />
</Entity>

// Blog post
<Entity>
  <Attribute name="title" factory={postFactory.title} />
  <Attribute name="slug" factory={postFactory.slug} />
  <Attribute name="content" factory={postFactory.content} />
  <Attribute name="excerpt" factory={postFactory.excerpt} />
  <Attribute name="publishedAt" factory={postFactory.publishedAt} />
</Entity>

// Product
<Entity>
  <Attribute name="name" factory={productFactory.name} />
  <Attribute name="description" factory={productFactory.description} />
  <Attribute name="price" factory={productFactory.price} />
  <Attribute name="sku" factory={productFactory.sku} />
  <Attribute name="inStock" factory={productFactory.inStock} />
</Entity>
```

## Available Factories

- `userFactory` - User/profile data
- `postFactory` - Blog posts/articles
- `productFactory` - E-commerce products
- `companyFactory` - Company information
- `addressFactory` - Physical addresses
- `commentFactory` - Comments/reviews
- `eventFactory` - Events/meetings
- `profileFactory` - Social profiles
- `orderFactory` - Orders/transactions
- `tagFactory` - Tags/categories

## API Reference

### Person

```typescript
faker.firstName()       // Generate first name
faker.lastName()        // Generate last name
faker.fullName()        // Generate full name
faker.jobTitle()        // Generate job title
```

### Internet

```typescript
faker.email()           // Generate email
faker.username()        // Generate username
faker.url()             // Generate URL
faker.avatar()          // Generate avatar URL
faker.password()        // Generate password
```

### Company

```typescript
faker.companyName()     // Generate company name
faker.catchPhrase()     // Generate catch phrase
faker.buzzword()        // Generate buzzword
```

### Address

```typescript
faker.streetAddress()   // Generate street address
faker.city()            // Generate city
faker.state()           // Generate state
faker.zipCode()         // Generate zip code
faker.country()         // Generate country
```

### Phone

```typescript
faker.phoneNumber()     // Generate phone number
```

### Lorem

```typescript
faker.word()            // Generate word
faker.words(5)          // Generate 5 words
faker.sentence()        // Generate sentence
faker.paragraph()       // Generate paragraph
faker.paragraphs(3)     // Generate 3 paragraphs
faker.text()            // Generate text
```

### Numbers

```typescript
faker.int({ min: 1, max: 100 })              // Generate integer
faker.float({ min: 0, max: 1, precision: 2 }) // Generate float
```

### Dates

```typescript
faker.pastDate({ years: 1 })                  // Generate past date
faker.futureDate({ years: 1 })                // Generate future date
faker.recentDate({ days: 30 })                // Generate recent date
faker.dateBetween(new Date('2020-01-01'), new Date()) // Generate date between
```

### Commerce

```typescript
faker.productName()         // Generate product name
faker.productDescription()  // Generate product description
faker.price()              // Generate price
faker.department()         // Generate department
```

### Finance

```typescript
faker.creditCardNumber()    // Generate credit card number
faker.iban()               // Generate IBAN
faker.currencyCode()       // Generate currency code
```

### Other

```typescript
faker.boolean()            // Generate boolean
faker.uuid()               // Generate UUID
faker.arrayElement(['a', 'b', 'c'])     // Pick random element
faker.arrayElements(['a', 'b', 'c'], 2) // Pick 2 random elements
faker.shuffle([1, 2, 3])                // Shuffle array
```

## Locale Support

Create a faker instance with a specific locale:

```typescript
import { createFaker } from '@seedts/faker';
import { faker as fakerDE } from '@faker-js/faker/locale/de';
import { faker as fakerFR } from '@faker-js/faker/locale/fr';

// Create German faker
const deFaker = createFaker(fakerDE);

// Create French faker
const frFaker = createFaker(fakerFR);

<Attribute name="name" factory={deFaker.fullName()} />
<Attribute name="city" factory={deFaker.city()} />
```

Available locales: `en`, `de`, `fr`, `es`, `it`, `pt`, `ru`, `zh_CN`, `ja`, `ko`, and many more. See [Faker.js locales](https://fakerjs.dev/guide/localization.html) for the full list.

## Advanced Usage

### Custom Combinations

```typescript
import { faker } from '@seedts/faker';

// Combine multiple faker methods
const customEmail: AttributeGenerator<string> = (ctx) => {
  const firstName = faker.instance.person.firstName();
  const lastName = faker.instance.person.lastName();
  return `${firstName}.${lastName}@example.com`.toLowerCase();
};

<Attribute name="email" factory={customEmail} />
```

### Context-aware Factories

```typescript
// Use context index for sequential data
const sequentialEmail: AttributeGenerator<string> = (ctx) => {
  return `user${ctx.index}@example.com`;
};

// Combine with faker for variety
const variedEmail: AttributeGenerator<string> = (ctx) => {
  const domain = faker.instance.internet.domainName();
  return `user${ctx.index}@${domain}`;
};
```

### Accessing Raw Faker Instance

```typescript
import { faker } from '@seedts/faker';

// Access the underlying Faker.js instance
const customFactory = () => {
  return faker.instance.helpers.fake('{{person.firstName}} {{person.lastName}}');
};
```

## TypeScript Support

All faker methods are fully typed:

```typescript
import { faker } from '@seedts/faker';
import type { AttributeGenerator } from '@seedts/types';

const emailGen: AttributeGenerator<string> = faker.email();
const ageGen: AttributeGenerator<number> = faker.int({ min: 18, max: 80 });
const activeGen: AttributeGenerator<boolean> = faker.boolean();
```

## Examples

### Complete User Seed

```typescript
import { faker, userFactory } from '@seedts/faker';

export const UsersSeed = ({ adapter }) => (
  <Seed name="users" adapter={adapter}>
    <Action count={100}>
      <Entity>
        <Attribute name="id" type="number" autoIncrement />
        <Attribute name="email" type="string" unique factory={userFactory.email} />
        <Attribute name="firstName" type="string" factory={userFactory.firstName} />
        <Attribute name="lastName" type="string" factory={userFactory.lastName} />
        <Attribute name="username" type="string" unique factory={userFactory.username} />
        <Attribute name="password" type="string" factory={userFactory.password} />
        <Attribute name="avatar" type="string" factory={userFactory.avatar} />
        <Attribute name="bio" type="string" factory={faker.paragraph(2)} />
        <Attribute name="phone" type="string" factory={userFactory.phone} />
        <Attribute name="age" type="number" factory={faker.int({ min: 18, max: 80 })} />
        <Attribute name="active" type="boolean" factory={faker.boolean()} />
        <Attribute name="createdAt" type="date" default={() => new Date()} />
      </Entity>
    </Action>
  </Seed>
);
```

## License

MIT