@drichdev/genata 1.0.4 → 1.0.5

package/README.md

@@ -2,17 +2,30 @@
 
 A lightweight, secure, and TypeScript-first library for generating realistic fake data for testing, development, and documentation.
 
-## 🚀 Features
+---
+
+## Features
+
+* Simple and intuitive API
+* Batch data generation
+* Reproducible data with seed support
+* Full TypeScript support
+* Built-in validation and sanitization
+* No runtime dependencies except `@faker-js/faker`
+* 25+ data generators
+
+---
+
+## Why Genata?
 
-- **Simple API**: `genata.email()`, `genata.firstName()`, etc.
-- **Batch Generation**: Generate multiple records at once
-- **Seeding Support**: Reproducible data with seed values
-- **Type-Safe**: Full TypeScript support with strict typing
-- **Secure**: Input validation and sanitization built-in
-- **No Dependencies**: Only depends on @faker-js/faker
-- **25+ Data Types**: From emails to credit cards
+* Cleaner and simpler API than typical faker usage
+* Built-in batch generation without extra tooling
+* Consistent seeding across all generators
+* Type-safe by default
+
+---
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @drichdev/genata
@@ -22,19 +35,31 @@ yarn add @drichdev/genata
 pnpm add @drichdev/genata
 ```
 
-## 🎯 Quick Start
+---
+
+## Import
+
+### ES Modules (recommended)
+
+```javascript
+import genata from '@drichdev/genata';
+```
 
-### CommonJS (Node.js)
+### CommonJS
 
 ```javascript
 const genata = require('@drichdev/genata');
+```
 
-const email = genata.email();
-const firstName = genata.firstName();
-const phone = genata.phone();
+### TypeScript
+
+```typescript
+import genata, { type FieldDefinition } from '@drichdev/genata';
 ```
 
-### ES Modules (Node.js with "type": "module")
+---
+
+## Quick Start
 
 ```javascript
 import genata from '@drichdev/genata';
@@ -44,30 +69,23 @@ const firstName = genata.firstName();
 const phone = genata.phone();
 ```
 
-### TypeScript / Next.js
+---
 
-```typescript
-import genata from '@drichdev/genata';
+## Naming Convention
 
-export default function Home() {
-  const email = genata.email();
-  const firstName = genata.firstName();
-  const phone = genata.phone();
-
-  return (
-    <div>
-      <p>Email: {email}</p>
-      <p>Name: {firstName}</p>
-      <p>Phone: {phone}</p>
-    </div>
-  );
-}
-```
+* Direct API uses camelCase
+  `genata.firstName()`
+
+* Batch generation uses snake_case
+  `type: "first_name"`
 
-### Using Generators by Category
+---
+
+## Generators
+
+### Person
 
 ```javascript
-// Person generators
 genata.person.firstName();
 genata.person.lastName();
 genata.person.fullName();
@@ -75,46 +93,64 @@ genata.person.email();
 genata.person.username();
 genata.person.password();
 genata.person.phone();
+```
 
-// Location generators
+### Location
+
+```javascript
 genata.location.address();
 genata.location.city();
 genata.location.country();
 genata.location.zipCode();
+```
+
+### Internet
 
-// Internet generators
+```javascript
 genata.internet.url();
 genata.internet.ipv4();
 genata.internet.ipv6();
 genata.internet.creditCard();
+```
 
-// Company generators
+### Company
+
+```javascript
 genata.company.company();
 genata.company.jobTitle();
+```
+
+### Date
 
-// Date generators
+```javascript
 genata.date.date();
 genata.date.dateTime();
 genata.date.futureDate();
+```
 
-// Data type generators
+### Data Types
+
+```javascript
 genata.datatype.uuid();
 genata.datatype.boolean();
 genata.datatype.integer({ min: 0, max: 100 });
 genata.datatype.float({ min: 0, max: 100, decimals: 2 });
 genata.datatype.color();
 genata.datatype.hex({ length: 16 });
+```
+
+### Text
 
-// Text generators
+```javascript
 genata.text.sentence();
 genata.text.paragraph({ sentences: 5 });
 genata.text.word();
 genata.text.slug();
 ```
 
-### Batch Generation
+---
 
-Generate multiple records at once:
+## Batch Generation
 
 ```javascript
 const fields = [
@@ -126,44 +162,22 @@ const fields = [
   { name: "createdAt", type: "datetime" },
 ];
 
-// Generate 100 records (default)
+// Default (100 records)
 const users = genata.generateBatch(fields);
 
-// Generate 1000 records
+// Custom count
 const largeDataset = genata.generateBatch(fields, { count: 1000 });
 
-// With progress tracking
+// With progress
 const data = genata.generateBatchWithProgress(fields, {
   count: 10000,
   onProgress: (progress) => console.log(`${progress}% complete`),
 });
 ```
 
-### Seeding for Reproducible Data
-
-```javascript
-// Set a seed for reproducible results
-genata.setSeed(12345);
-
-const email1 = genata.email(); // Always the same value
-const email2 = genata.email(); // Always the same value
-
-// Reset to random generation
-genata.resetSeed();
-```
-
-## 🔒 Security Features
-
-- **Input Validation**: All options are validated before use
-- **Sanitization**: User inputs are sanitized to prevent injection
-- **Type Safety**: TypeScript strict mode ensures type correctness
-- **Error Handling**: Proper error messages for invalid inputs
-- **No Shell Execution**: No dynamic code execution
-- **Immutable Defaults**: Safe default values that can't be modified
-
-## 📋 Available Field Types
+---
 
-When using batch generation, supported field types are:
+## Supported Field Types
 
 ```
 Person: first_name, last_name, full_name, email, username, password, phone
@@ -175,191 +189,180 @@ Data Types: uuid, boolean, int, float, number, zero_one, id_increment, color, he
 Text: sentence, paragraph, word, slug
 ```
 
-## 🎛️ API Reference
+---
+
+## Seeding (Reproducible Data)
+
+```javascript
+genata.setSeed(12345);
+
+const email1 = genata.email();
+const email2 = genata.email();
+
+// Reset randomness
+genata.resetSeed();
+```
+
+---
 
-### Core Methods
+## API Reference
 
-#### `genata.email()`
+### `genata.email()`
 
-Generate a random email address.
+Generate a random email.
 
 ```javascript
 const email = genata.email();
-// "alice.johnson@example.com"
 ```
 
-#### `genata.generateBatch(fields, options?)`
+---
+
+### `genata.generateBatch(fields, options?)`
 
 Generate multiple records.
 
 **Parameters:**
 
-- `fields` (FieldDefinition[]): Array of field definitions
-- `options` (BatchGeneratorOptions?):
-  - `count` (number): Number of records to generate (default: 100)
-  - `seed` (number): Seed for reproducible data
-  - `locale` (string): Locale for faker
+* `fields`: Array of field definitions
+* `options`:
 
-**Returns:** Array of objects with generated data
+  * `count` (default: 100)
+  * `seed`
+  * `locale`
 
-#### `genata.setSeed(seed)`
+**Returns:** Array of objects
 
-Set a seed for reproducible data generation.
+---
 
-**Parameters:**
+### `genata.setSeed(seed)`
 
-- `seed` (number): Non-negative integer seed value
+Set a seed for reproducible results.
 
-#### `genata.resetSeed()`
+---
 
-Reset to random generation without a seed.
+### `genata.resetSeed()`
 
-## 🏗️ Architecture
+Reset random generation.
 
-The library is organized into modules:
+---
 
-- **generators**: Data generation logic (basic, batch, field-level)
-- **types**: TypeScript type definitions
-- **validators**: Input validation and sanitization
-- **utils**: Helper functions (faker initialization)
+## Examples
 
-## 🧪 Testing
+### Generate Users
 
-```bash
-npm test
+```javascript
+const users = genata.generateBatch(
+  [
+    { name: "id", type: "id_increment" },
+    { name: "email", type: "email" },
+    { name: "firstName", type: "first_name" },
+    { name: "lastName", type: "last_name" },
+    { name: "phone", type: "phone" },
+    { name: "company", type: "company" },
+    { name: "jobTitle", type: "job_title" },
+    { name: "createdAt", type: "datetime" },
+  ],
+  { count: 50 }
+);
 ```
 
-## 📄 License
+---
 
-MIT
+### Generate Products
 
-## 🤝 Contributing
+```javascript
+const products = genata.generateBatch(
+  [
+    { name: "id", type: "uuid" },
+    { name: "name", type: "sentence" },
+    { name: "description", type: "paragraph", options: { sentences: 3 } },
+    { name: "price", type: "float", options: { min: 10, max: 1000, decimals: 2 } },
+    { name: "stock", type: "int", options: { min: 0, max: 1000 } },
+    { name: "color", type: "color" },
+  ],
+  { count: 20 }
+);
+```
 
-Contributions are welcome! Please ensure:
+---
 
-- All code is TypeScript
-- Security-first approach
-- Input validation for all public methods
-- Comprehensive error messages
+### Reproducible Tests
 
-## 📚 Examples
+```javascript
+beforeEach(() => {
+  genata.setSeed(42);
+});
 
-### Generate Test Users
+const user1 = { email: genata.email() };
 
-```javascript
-import genata from "genata";
-
-const generateTestUsers = (count = 10) => {
-  return genata.generateBatch(
-    [
-      { name: "id", type: "id_increment" },
-      { name: "email", type: "email" },
-      { name: "firstName", type: "first_name" },
-      { name: "lastName", type: "last_name" },
-      { name: "phone", type: "phone" },
-      { name: "company", type: "company" },
-      { name: "jobTitle", type: "job_title" },
-      { name: "createdAt", type: "datetime" },
-    ],
-    { count }
-  );
-};
-
-const users = generateTestUsers(50);
-console.log(users);
+genata.setSeed(42);
+const user2 = { email: genata.email() };
 ```
 
-### Generate E-commerce Products
+---
 
-```javascript
-const generateProducts = (count = 20) => {
-  return genata.generateBatch(
-    [
-      { name: "id", type: "uuid" },
-      { name: "name", type: "sentence" },
-      { name: "description", type: "paragraph", options: { sentences: 3 } },
-      { name: "price", type: "float", options: { min: 10, max: 1000, decimals: 2 } },
-      { name: "stock", type: "int", options: { min: 0, max: 1000 } },
-      { name: "color", type: "color" },
-    ],
-    { count }
-  );
-};
-```
+## Security
 
-### Reproducible Data for Tests
+* Input validation on all public methods
+* Sanitization of user-provided options
+* No dynamic code execution
+* Safe default values
 
-```javascript
-describe("User Service", () => {
-  beforeEach(() => {
-    genata.setSeed(42);
-  });
-
-  test("should process user data consistently", () => {
-    const user1 = { email: genata.email() };
-    
-    genata.setSeed(42);
-    const user2 = { email: genata.email() };
-
-    expect(user1.email).toBe(user2.email);
-  });
-});
-```
+---
 
-## 🐛 Troubleshooting
+## Architecture
 
-### "Invalid field type" error
+* `generators`: data generation logic
+* `types`: TypeScript definitions
+* `validators`: input validation
+* `utils`: internal helpers
 
-Make sure you're using a valid field type from the supported list.
+---
 
-### Data is not reproducible with seed
+## Testing
 
-Make sure to set the seed before generating data and don't mix generator calls without resetting.
+```bash
+npm test
+```
 
-### Performance issues with large batches
+---
 
-For very large batches (>100K records), consider:
+## Troubleshooting
 
-- Generating in chunks
-- Using `generateBatchWithProgress` to show progress
-- Running in a worker thread if in browser
+### Invalid field type
 
-## 📚 Complete Documentation
+Ensure the field type exists in the supported list.
 
-For detailed examples and advanced usage, see [USAGE.md](./USAGE.md)
+### Seed not working
 
-## 🔧 Import Methods
+Set the seed before generating data and avoid mixing seeded and non-seeded calls.
 
-### CommonJS
-```javascript
-const genata = require('@drichdev/genata');
-genata.email();
-```
+### Performance issues
 
-### ES Modules
-```javascript
-import genata from '@drichdev/genata';
-genata.email();
-```
+For very large datasets:
 
-### TypeScript
-```typescript
-import genata, { type FieldDefinition } from '@drichdev/genata';
-```
+* Generate in chunks
+* Use progress tracking
+* Consider worker threads in browser environments
 
-### Next.js / React
-```typescript
-import genata from '@drichdev/genata';
+---
 
-export default function Component() {
-  const data = genata.email();
-  return <div>{data}</div>;
-}
-```
+## Contributing
+
+* TypeScript only
+* Validate all inputs
+* Maintain strong error handling
+* Follow a security-first approach
+
+
+---
+
+## Documentation
 
-**⚠️ Note**: If you get a "Module type is not specified" warning, add `"type": "module"` to your `package.json` or use CommonJS require instead.
+See [USAGE.md](./USAGE.md) for advanced usage.
 
 ---
 
-Made with ❤️ by Drichdev
+## Author
 
+Created by Drichdev

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drichdev/genata",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Generate realistic fake data easily",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",