pi-harness-runtime 0.5.0 → 0.6.3-beta.13

package/packages/test-data-generator/README.md

@@ -0,0 +1,365 @@
+# @pi/test-data-generator
+
+Generate realistic test data with schema definitions, fixtures, and multiple export formats.
+
+## Features
+
+- **Schema-Based Generation** - Define data schemas with field types and options
+- **50+ Field Types** - Pre-built generators for names, addresses, emails, etc.
+- **Custom Generators** - Add your own field generators
+- **Bulk Generation** - Generate thousands of records at once
+- **Seed Support** - Reproducible data with seeded random
+- **Relationships** - Define relations between schemas
+- **Hooks** - Pre/post generation hooks for data transformation
+- **Multiple Export Formats** - JSON, CSV, SQL, YAML, and fixtures
+- **TypeScript Support** - Full type definitions
+
+## Installation
+
+```bash
+npm install @pi/test-data-generator
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { createTestDataGenerator } from "@pi/test-data-generator";
+
+const generator = createTestDataGenerator({
+  seed: 12345, // For reproducibility
+});
+
+// Generate users
+const result = await generator.generate({
+  schema: {
+    name: "User",
+    fields: [
+      { name: "email", type: "email" },
+      { name: "firstName", type: "firstName" },
+      { name: "lastName", type: "lastName" },
+      { name: "age", type: "number", options: { min: 18, max: 99 } },
+      { name: "isActive", type: "boolean" },
+      { name: "createdAt", type: "datetime", options: { past: true } },
+    ],
+  },
+  count: 10,
+});
+
+console.log(result.records[0].data);
+// {
+//   email: "john.smith@example.com",
+//   firstName: "John",
+//   lastName: "Smith",
+//   age: 42,
+//   isActive: true,
+//   createdAt: "2024-01-15T10:30:00.000Z"
+// }
+```
+
+### Field Types
+
+```typescript
+// Basic types
+{ name: "name", type: "string" }
+{ name: "count", type: "number", options: { min: 1, max: 100 } }
+{ name: "active", type: "boolean" }
+
+// Identity
+{ name: "email", type: "email" }
+{ name: "phone", type: "phone" }
+{ name: "uuid", type: "uuid" }
+{ name: "userName", type: "userName" }
+{ name: "password", type: "password", options: { minLength: 16 } }
+
+// Person
+{ name: "firstName", type: "firstName" }
+{ name: "lastName", type: "lastName" }
+{ name: "fullName", type: "fullName" }
+{ name: "avatar", type: "avatar" }
+
+// Location
+{ name: "address", type: "address" }
+{ name: "city", type: "city" }
+{ name: "country", type: "country" }
+{ name: "zipCode", type: "zipCode" }
+
+// Company
+{ name: "company", type: "company" }
+{ name: "department", type: "department" }
+{ name: "jobTitle", type: "jobTitle" }
+
+// Text
+{ name: "bio", type: "paragraph" }
+{ name: "headline", type: "sentence" }
+{ name: "tag", type: "word" }
+
+// Network
+{ name: "website", type: "url" }
+{ name: "ip", type: "ipv4" }
+
+// Financial
+{ name: "card", type: "creditCard" }
+{ name: "currency", type: "currency" }
+
+// Enum
+{ name: "status", type: "enum", options: { values: ["pending", "active", "closed"] } }
+
+// Array
+{ name: "tags", type: "array", options: { itemType: "word", maxItems: 5 } }
+```
+
+### Field Options
+
+```typescript
+// String options
+{ name: "code", type: "string", options: { minLength: 8, maxLength: 16, uppercase: true } }
+
+// Number options
+{ name: "score", type: "number", options: { min: 0, max: 100, integer: true } }
+
+// Date options
+{ name: "created", type: "date", options: { past: true } }
+{ name: "expires", type: "date", options: { future: true } }
+{ name: "birthDate", type: "date", options: { maxDate: "2005-01-01" } }
+
+// Enum with weights
+{ name: "role", type: "enum", options: {
+  values: ["admin", "user", "guest"],
+  weights: [0.1, 0.7, 0.2]  // 10% admin, 70% user, 20% guest
+}}
+```
+
+### Schema Registration
+
+```typescript
+const generator = createTestDataGenerator();
+
+// Register schema
+generator.registerSchema({
+  name: "Product",
+  fields: [
+    { name: "name", type: "string" },
+    { name: "price", type: "number", options: { min: 1, max: 1000 } },
+    { name: "sku", type: "uuid" },
+    { name: "inStock", type: "boolean" },
+  ],
+});
+
+// Use by name
+const products = await generator.generate({
+  schemaId: "Product",
+  count: 100,
+});
+```
+
+### Hooks
+
+```typescript
+const schema = {
+  name: "Order",
+  fields: [
+    { name: "id", type: "uuid" },
+    { name: "total", type: "number" },
+    { name: "status", type: "enum", options: { values: ["pending", "completed"] } },
+  ],
+  hooks: {
+    beforeCreate: (data) => ({
+      ...data,
+      createdAt: new Date().toISOString(),
+    }),
+    afterCreate: (data) => ({
+      ...data,
+      reference: `ORD-${data.id.slice(0, 8)}`,
+    }),
+  },
+};
+```
+
+### Data Overrides
+
+```typescript
+// Generate with specific values
+const result = await generator.generate({
+  schema,
+  count: 5,
+  data: {
+    isAdmin: true,  // Override all records
+  },
+});
+
+// Per-record overrides
+const result = await generator.generate({
+  schema,
+  count: 3,
+  data: [
+    { email: "admin@example.com" },    // Record 0
+    { email: "user1@example.com" },    // Record 1
+    { email: "user2@example.com" },    // Record 2
+  ],
+});
+```
+
+### Export Formats
+
+```typescript
+import { exportToJson, exportToCsv, exportToSql } from "@pi/test-data-generator";
+
+// Export as JSON
+const json = exportToJson(result.records, { pretty: true });
+
+// Export as CSV
+const csv = exportToCsv(result.records, ["email", "name", "age"]);
+
+// Export as SQL INSERT statements
+const sql = exportToSql(result.records, "users");
+```
+
+### Seeding
+
+```typescript
+// Same seed = same data
+const gen1 = createTestDataGenerator({ seed: 12345 });
+const gen2 = createTestDataGenerator({ seed: 12345 });
+
+const result1 = await gen1.generate({ schema, count: 10 });
+const result2 = await gen2.generate({ schema, count: 10 });
+
+console.log(result1.records[0].data.email === result2.records[0].data.email); // true
+```
+
+## API Reference
+
+### TestDataGenerator
+
+```typescript
+const generator = createTestDataGenerator({
+  seed?: number;          // Random seed
+  locale?: string;        // Data locale (default: "en")
+  verbose?: boolean;       // Enable logging
+  maxRetries?: number;    // Max generation attempts
+  customGenerators?: Record<string, CustomGenerator>;
+});
+```
+
+### Methods
+
+```typescript
+// Register schema
+generator.registerSchema(schema: Schema): void;
+
+// Get registered schema
+generator.getSchema(name: string): Schema | undefined;
+
+// Generate data
+generator.generate(request: GenerationRequest): Promise<GenerationResult>;
+
+// Get faker instance
+generator.getFaker(): SimpleFaker;
+
+// Set seed
+generator.setSeed(seed: number): void;
+
+// Register custom generator
+generator.registerCustomGenerator(name: string, generator: CustomGenerator): void;
+```
+
+### Schema
+
+```typescript
+interface Schema {
+  name: string;
+  fields: FieldDefinition[];
+  relations?: RelationDefinition[];
+  hooks?: SchemaHooks;
+}
+```
+
+### FieldDefinition
+
+```typescript
+interface FieldDefinition {
+  name: string;
+  type: FieldType;
+  options?: FieldOptions;
+  required?: boolean;
+  default?: unknown;
+  validate?: FieldValidator;
+}
+```
+
+### GenerationResult
+
+```typescript
+interface GenerationResult {
+  success: boolean;
+  records: GeneratedRecord[];
+  count: number;
+  generationTimeMs: number;
+  errors?: GenerationError[];
+}
+```
+
+## Field Types Reference
+
+| Type | Description | Example |
+| ------ | ------------- | --------- |
+| `string` | Random string | "xK9mP2nL" |
+| `number` | Random number | 42 |
+| `boolean` | Random boolean | true |
+| `date` | Random date | "2024-01-15T10:30:00Z" |
+| `email` | Email address | "<john@example.com>" |
+| `url` | URL | "<https://example.com>" |
+| `phone` | Phone number | "(555) 123-4567" |
+| `uuid` | UUID v4 | "550e8400-e29b-41d4-a716-446655440000" |
+| `firstName` | First name | "John" |
+| `lastName` | Last name | "Smith" |
+| `fullName` | Full name | "John Smith" |
+| `address` | Street address | "123 Main St" |
+| `city` | City | "New York" |
+| `country` | Country | "United States" |
+| `zipCode` | Zip code | "10001" |
+| `company` | Company name | "Acme Corp" |
+| `department` | Department | "Engineering" |
+| `jobTitle` | Job title | "Software Engineer" |
+| `paragraph` | Paragraph | "Lorem ipsum dolor sit amet..." |
+| `sentence` | Sentence | "Lorem ipsum dolor." |
+| `word` | Single word | "lorem" |
+| `image` | Image URL | "<https://picsum.photos/640/480>" |
+| `avatar` | Avatar URL | "<https://api.dicebear.com/>..." |
+| `color` | Color name | "blue" |
+| `hexColor` | Hex color | "#3498db" |
+| `ipv4` | IPv4 address | "192.168.1.1" |
+| `ipv6` | IPv6 address | "2001:0db8:..." |
+| `userName` | Username | "johnsmith42" |
+| `password` | Password | "xK9mP2nL4..." |
+| `creditCard` | Credit card | "4111234567890123" |
+| `currency` | Currency code | "USD" |
+| `fileName` | File name | "document.pdf" |
+| `filePath` | File path | "/home/user/docs/file.txt" |
+| `mimeType` | MIME type | "application/json" |
+| `latitude` | Latitude | 40.7128 |
+| `longitude` | Longitude | -74.0060 |
+| `enum` | Enum value | "active" |
+| `array` | Array of values | ["tag1", "tag2"] |
+| `object` | Nested object | { name: "John" } |
+| `custom` | Custom generator | custom function |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                 TestDataGenerator                         │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
+│  │   Schema   │  │   Faker    │  │   Generator    │  │
+│  │   Manager  │──│   Adapter  │──│   Engine      │  │
+│  └─────────────┘  └─────────────┘  └─────────────────┘  │
+│         │                                       │        │
+│         ▼                                       ▼        │
+│  ┌─────────────┐                       ┌─────────────────┐│
+│  │   Field    │                       │  Generation    ││
+│  │  Validators│                       │  Results       ││
+│  └─────────────┘                       └─────────────────┘│
+└─────────────────────────────────────────────────────────┘
+```

package/packages/test-data-generator/dist/faker-adapter.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Test Data Generator - Faker Adapter
+ *
+ * Simple faker implementation for data generation.
+ */
+import type { FakerAdapter, DateOptions } from "./types.js";
+export declare class SimpleFaker implements FakerAdapter {
+    private random;
+    constructor(seed?: number, _locale?: string);
+    /**
+     * Pick random element from array
+     */
+    pick<T>(array: T[]): T;
+    /**
+     * Generate random string
+     */
+    string(min?: number, max?: number): string;
+    /**
+     * Generate random number
+     */
+    number(min?: number, max?: number): number;
+    /**
+     * Generate random boolean
+     */
+    boolean(): boolean;
+    /**
+     * Generate random date
+     */
+    date(options?: DateOptions): Date;
+    /**
+     * Generate email
+     */
+    email(): string;
+    /**
+     * Generate URL
+     */
+    url(): string;
+    /**
+     * Generate phone number
+     */
+    phone(): string;
+    /**
+     * Generate UUID
+     */
+    uuid(): string;
+    /**
+     * Generate first name
+     */
+    firstName(): string;
+    /**
+     * Generate last name
+     */
+    lastName(): string;
+    /**
+     * Generate full name
+     */
+    fullName(): string;
+    /**
+     * Generate address
+     */
+    address(): string;
+    /**
+     * Generate city
+     */
+    city(): string;
+    /**
+     * Generate country
+     */
+    country(): string;
+    /**
+     * Generate zip code
+     */
+    zipCode(): string;
+    /**
+     * Generate company name
+     */
+    company(): string;
+    /**
+     * Generate department
+     */
+    department(): string;
+    /**
+     * Generate job title
+     */
+    jobTitle(): string;
+    /**
+     * Generate paragraph
+     */
+    paragraph(sentences?: number): string;
+    /**
+     * Generate sentence
+     */
+    sentence(): string;
+    /**
+     * Generate word
+     */
+    word(): string;
+    /**
+     * Generate lorem text
+     */
+    lorem(words?: number): string;
+    /**
+     * Generate image URL
+     */
+    image(width?: number, height?: number): string;
+    /**
+     * Generate avatar URL
+     */
+    avatar(): string;
+    /**
+     * Generate color name
+     */
+    color(): string;
+    /**
+     * Generate hex color
+     */
+    hexColor(): string;
+    /**
+     * Generate IPv4 address
+     */
+    ipv4(): string;
+    /**
+     * Generate IPv6 address
+     */
+    ipv6(): string;
+    /**
+     * Generate username
+     */
+    userName(): string;
+    /**
+     * Generate password
+     */
+    password(length?: number): string;
+    /**
+     * Generate credit card number (fake)
+     */
+    creditCard(): string;
+    /**
+     * Generate currency code
+     */
+    currency(): string;
+    /**
+     * Generate locale
+     */
+    locale(): string;
+    /**
+     * Generate file name
+     */
+    fileName(ext?: string): string;
+    /**
+     * Generate file path
+     */
+    filePath(): string;
+    /**
+     * Generate MIME type
+     */
+    mimeType(): string;
+    /**
+     * Generate latitude
+     */
+    latitude(): number;
+    /**
+     * Generate longitude
+     */
+    longitude(): number;
+    /**
+     * Set seed for reproducibility
+     */
+    setSeed(seed: number): void;
+}
+/**
+ * Create a faker adapter
+ */
+export declare function createFaker(seed?: number, locale?: string): FakerAdapter;
+//# sourceMappingURL=faker-adapter.d.ts.map

package/packages/test-data-generator/dist/faker-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"faker-adapter.d.ts","sourceRoot":"","sources":["../src/faker-adapter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA+N5D,qBAAa,WAAY,YAAW,YAAY;IAC/C,OAAO,CAAC,MAAM,CAAe;gBAEjB,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,MAAa;IAIjD;;OAEG;IACH,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC;IAItB;;OAEG;IACH,MAAM,CAAC,GAAG,SAAI,EAAE,GAAG,SAAK,GAAG,MAAM;IAUjC;;OAEG;IACH,MAAM,CAAC,GAAG,SAAI,EAAE,GAAG,SAAM,GAAG,MAAM;IAIlC;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IA2BjC;;OAEG;IACH,KAAK,IAAI,MAAM;IAUf;;OAEG;IACH,GAAG,IAAI,MAAM;IAMb;;OAEG;IACH,KAAK,IAAI,MAAM;IAOf;;OAEG;IACH,IAAI,IAAI,MAAM;IAed;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,OAAO,IAAI,MAAM;IAOjB;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,SAAS,CAAC,SAAS,SAAI,GAAG,MAAM;IAQhC;;OAEG;IACH,QAAQ,IAAI,MAAM;IAalB;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,KAAK,CAAC,KAAK,SAAK,GAAG,MAAM;IAQzB;;OAEG;IACH,KAAK,CAAC,KAAK,SAAM,EAAE,MAAM,SAAM,GAAG,MAAM;IAIxC;;OAEG;IACH,MAAM,IAAI,MAAM;IAKhB;;OAEG;IACH,KAAK,IAAI,MAAM;IAqBf;;OAEG;IACH,QAAQ,IAAI,MAAM;IAKlB;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,IAAI,IAAI,MAAM;IAMd;;OAEG;IACH,QAAQ,IAAI,MAAM;IASlB;;OAEG;IACH,QAAQ,CAAC,MAAM,SAAK,GAAG,MAAM;IAU7B;;OAEG;IACH,UAAU,IAAI,MAAM;IAUpB;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,MAAM,IAAI,MAAM;IAKhB;;OAEG;IACH,QAAQ,CAAC,GAAG,SAAQ,GAAG,MAAM;IAK7B;;OAEG;IACH,QAAQ,IAAI,MAAM;IAYlB;;OAEG;IACH,QAAQ,IAAI,MAAM;IAiBlB;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;CAG3B;AAID;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAExE"}