@jackchuka/gql-ingest 1.0.0

package/README.md

@@ -0,0 +1,150 @@
+# GQL Ingest
+
+[![npm version](https://badge.fury.io/js/%40jackchuka%2Fgql-ingest.svg)](https://badge.fury.io/js/%40jackchuka%2Fgql-ingest)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A TypeScript CLI tool that reads CSV files and ingests data into GraphQL APIs through configurable mutations.
+
+## Features
+
+- ✅ External GraphQL mutation definitions (separate .graphql files)
+- ✅ CSV-to-GraphQL variable mapping via JSON configuration
+- ✅ Configurable GraphQL endpoint and headers
+
+## Installation
+
+### For End Users
+
+```bash
+# Install globally
+npm install -g @jackchuka/gql-ingest
+
+# Or use with npx (no installation required)
+npx @jackchuka/gql-ingest --endpoint <url> --config <path>
+```
+
+### For Development
+
+```bash
+git clone https://github.com/jackchuka/gql-ingest.git
+cd gql-ingest
+npm install
+npm run build
+```
+
+## Usage
+
+### CLI Options
+
+```bash
+gql-ingest [options]
+
+Options:
+  -V, --version            output the version number
+  -e, --endpoint <url>     GraphQL endpoint URL (required)
+  -c, --config <path>      Path to configuration directory (required)
+  -h, --headers <headers>  JSON string of headers to include in requests
+  --help                   display help for command
+```
+
+### Examples
+
+```bash
+# Basic usage
+npx @jackchuka/gql-ingest \
+  --endpoint https://your-graphql-api.com/graphql \
+  --config ./examples/demo
+
+# With authentication headers
+npx @jackchuka/gql-ingest \
+  --endpoint https://your-graphql-api.com/graphql \
+  --config ./examples/demo \
+  --headers '{"Authorization": "Bearer YOUR_TOKEN"}'
+
+# With custom headers
+npx @jackchuka/gql-ingest \
+  --endpoint https://api.example.com/graphql \
+  --config ./my-config \
+  --headers '{"X-API-Key": "your-api-key", "Content-Type": "application/json"}'
+```
+
+## Configuration
+
+The `--config` flag points to a configuration directory containing three subdirectories:
+
+- `data/` - CSV files with actual data
+- `graphql/` - GraphQL mutation definitions
+- `mappings/` - JSON files that map CSV columns to GraphQL variables
+
+Each entity has three corresponding files across these directories with matching names.
+
+### Example Configuration
+
+**examples/demo/mappings/items.json**:
+
+```json
+{
+  "csvFile": "data/items.csv",
+  "graphqlFile": "graphql/items.graphql",
+  "mapping": {
+    "name": "item_name",
+    "sku": "item_sku"
+  }
+}
+```
+
+**examples/demo/data/items.csv**:
+
+```csv
+item_name,item_sku
+Item1,item-1-sku
+Item2,item-2-sku
+```
+
+**examples/demo/graphql/items.graphql**:
+
+```graphql
+mutation CreateItem($name: String!, $sku: String!) {
+  createItem(input: { name: $name, sku: $sku }) {
+    id
+    name
+    sku
+  }
+}
+```
+
+## Development
+
+### Scripts
+
+```bash
+npm run build        # Build CLI bundle with esbuild
+npm run build:types  # Generate TypeScript declarations
+npm run build:all    # Build bundle + types
+npm run dev          # Run in development mode
+npm run test         # Run test suite
+npm run test:watch   # Run tests in watch mode
+npm run test:coverage # Run tests with coverage report
+```
+
+### Testing
+
+The project includes comprehensive unit tests for all modules:
+
+```bash
+npm test              # Run all tests
+```
+
+## How It Works
+
+1. **Discovery**: The tool scans the `mappings/` directory for `.json` files
+2. **Processing**: For each mapping file:
+   - Reads the corresponding CSV data file
+   - Loads the GraphQL mutation definition
+   - Maps CSV columns to GraphQL variables
+   - Executes the mutation for each CSV row
+3. **Error Handling**: Failed mutations are logged but don't stop processing
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/csv-reader.d.ts

@@ -0,0 +1,5 @@
+export interface CsvRow {
+    [key: string]: string;
+}
+export declare function readCsvFile(filePath: string): Promise<CsvRow[]>;
+//# sourceMappingURL=csv-reader.d.ts.map

package/dist/csv-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv-reader.d.ts","sourceRoot":"","sources":["../src/csv-reader.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,MAAM;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAUrE"}

package/dist/csv-reader.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=csv-reader.test.d.ts.map

package/dist/csv-reader.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv-reader.test.d.ts","sourceRoot":"","sources":["../src/csv-reader.test.ts"],"names":[],"mappings":""}

package/dist/graphql-client.d.ts

@@ -0,0 +1,7 @@
+export declare class GraphQLClientWrapper {
+    private client;
+    constructor(endpoint: string, headers?: Record<string, string>);
+    executeMutation(mutation: string, variables: Record<string, any>): Promise<any>;
+    setHeaders(headers: Record<string, string>): void;
+}
+//# sourceMappingURL=graphql-client.d.ts.map

package/dist/graphql-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-client.d.ts","sourceRoot":"","sources":["../src/graphql-client.ts"],"names":[],"mappings":"AAEA,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAgB;gBAElB,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAMxD,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IAUrF,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAG3C"}

package/dist/graphql-client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=graphql-client.test.d.ts.map

package/dist/graphql-client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-client.test.d.ts","sourceRoot":"","sources":["../src/graphql-client.test.ts"],"names":[],"mappings":""}

package/dist/mapper.d.ts

@@ -0,0 +1,15 @@
+import { GraphQLClientWrapper } from './graphql-client';
+export interface MappingConfig {
+    csvFile: string;
+    graphqlFile: string;
+    mapping: Record<string, string>;
+}
+export declare class DataMapper {
+    private client;
+    private basePath;
+    constructor(client: GraphQLClientWrapper, basePath?: string);
+    discoverMappings(configDir: string): string[];
+    processEntity(configPath: string): Promise<void>;
+    private mapCsvRowToVariables;
+}
+//# sourceMappingURL=mapper.d.ts.map

package/dist/mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapper.d.ts","sourceRoot":"","sources":["../src/mapper.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,EAAE,oBAAoB,EAAE,QAAQ,GAAE,MAAsB;IAK1E,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;IAiBvC,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BtD,OAAO,CAAC,oBAAoB;CAW7B"}

package/dist/mapper.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mapper.test.d.ts.map

package/dist/mapper.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapper.test.d.ts","sourceRoot":"","sources":["../src/mapper.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@jackchuka/gql-ingest",
+  "version": "1.0.0",
+  "description": "A CLI tool for ingesting data from CSV files into a GraphQL API",
+  "main": "dist/cli.js",
+  "bin": {
+    "gql-ingest": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "node esbuild.config.js",
+    "build:types": "tsc --emitDeclarationOnly",
+    "build:all": "npm run build && npm run build:types",
+    "dev": "ts-node src/cli.ts",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "prepublishOnly": "npm run build:all"
+  },
+  "keywords": [
+    "graphql",
+    "cli",
+    "csv",
+    "ingest",
+    "api"
+  ],
+  "author": "jackchuka",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jackchuka/gql-ingest.git"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "csv-parser": "^3.0.0",
+    "graphql-request": "^7.2.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.4",
+    "esbuild": "^0.25.5",
+    "jest": "^30.0.3",
+    "ts-jest": "^29.4.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.3.0"
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*"
+  ]
+}

package/src/cli.ts

@@ -0,0 +1,60 @@
+import { Command } from "commander";
+import { GraphQLClientWrapper } from "./graphql-client";
+import { DataMapper } from "./mapper";
+
+const program = new Command();
+
+program
+  .name("gql-ingest")
+  .description(
+    "A CLI tool for ingesting data from CSV files into a GraphQL API"
+  )
+  .version(require("../package.json").version);
+
+program
+  .requiredOption("-e, --endpoint <url>", "GraphQL endpoint URL")
+  .requiredOption(
+    "-c, --config <path>",
+    "Path to configuration directory (containing data/, graphql/, mappings/ subdirectories)"
+  )
+  .option(
+    "-h, --headers <headers>",
+    "JSON string of headers to include in requests"
+  )
+  .action(async (options) => {
+    try {
+      console.log("Starting seed data generation...");
+
+      // Parse headers if provided
+      const headers = options.headers ? JSON.parse(options.headers) : {};
+
+      // Initialize GraphQL client
+      const client = new GraphQLClientWrapper(options.endpoint, headers);
+
+      // Initialize data mapper
+      const mapper = new DataMapper(client);
+
+      // Discover all mapping files dynamically
+      const mappingPaths = mapper.discoverMappings(options.config);
+
+      if (mappingPaths.length === 0) {
+        console.warn(`No mapping files found in ${options.config}/mappings`);
+        return;
+      }
+
+      for (const configPath of mappingPaths) {
+        try {
+          await mapper.processEntity(configPath);
+        } catch (error) {
+          console.warn(`Warning: Could not process ${configPath}:`, error);
+        }
+      }
+
+      console.log("Seed data generation completed!");
+    } catch (error) {
+      console.error("Error:", error);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/csv-reader.test.ts

@@ -0,0 +1,82 @@
+import fs from "fs";
+import path from "path";
+import { readCsvFile } from "./csv-reader";
+
+describe("CSV Reader", () => {
+  const testDataDir = path.join(__dirname, "test-data");
+  const testCsvPath = path.join(testDataDir, "test.csv");
+
+  beforeAll(() => {
+    if (!fs.existsSync(testDataDir)) {
+      fs.mkdirSync(testDataDir, { recursive: true });
+    }
+  });
+
+  afterAll(() => {
+    if (fs.existsSync(testDataDir)) {
+      fs.rmSync(testDataDir, { recursive: true });
+    }
+  });
+
+  beforeEach(() => {
+    if (fs.existsSync(testCsvPath)) {
+      fs.unlinkSync(testCsvPath);
+    }
+  });
+
+  it("should read a simple CSV file", async () => {
+    const csvContent = "name,age\nJohn,30\nJane,25";
+    fs.writeFileSync(testCsvPath, csvContent);
+
+    const result = await readCsvFile(testCsvPath);
+
+    expect(result).toEqual([
+      { name: "John", age: "30" },
+      { name: "Jane", age: "25" },
+    ]);
+  });
+
+  it("should read CSV with special characters", async () => {
+    const csvContent =
+      'name,description\n"John Doe","A person with, comma"\n"Jane\'s Data","Quote test"';
+    fs.writeFileSync(testCsvPath, csvContent);
+
+    const result = await readCsvFile(testCsvPath);
+
+    expect(result).toEqual([
+      { name: "John Doe", description: "A person with, comma" },
+      { name: "Jane's Data", description: "Quote test" },
+    ]);
+  });
+
+  it("should handle empty CSV file", async () => {
+    const csvContent = "name,age\n";
+    fs.writeFileSync(testCsvPath, csvContent);
+
+    const result = await readCsvFile(testCsvPath);
+
+    expect(result).toEqual([]);
+  });
+
+  it("should handle CSV with only headers", async () => {
+    const csvContent = "name,age";
+    fs.writeFileSync(testCsvPath, csvContent);
+
+    const result = await readCsvFile(testCsvPath);
+
+    expect(result).toEqual([]);
+  });
+
+  it("should handle CSV with missing values", async () => {
+    const csvContent = "name,age,city\nJohn,30,\nJane,,Boston\n,25,NYC";
+    fs.writeFileSync(testCsvPath, csvContent);
+
+    const result = await readCsvFile(testCsvPath);
+
+    expect(result).toEqual([
+      { name: "John", age: "30", city: "" },
+      { name: "Jane", age: "", city: "Boston" },
+      { name: "", age: "25", city: "NYC" },
+    ]);
+  });
+});

package/src/csv-reader.ts

@@ -0,0 +1,18 @@
+import fs from 'fs';
+import csv from 'csv-parser';
+
+export interface CsvRow {
+  [key: string]: string;
+}
+
+export async function readCsvFile(filePath: string): Promise<CsvRow[]> {
+  return new Promise((resolve, reject) => {
+    const results: CsvRow[] = [];
+    
+    fs.createReadStream(filePath)
+      .pipe(csv())
+      .on('data', (data) => results.push(data))
+      .on('end', () => resolve(results))
+      .on('error', (error) => reject(error));
+  });
+}

package/src/graphql-client.test.ts

@@ -0,0 +1,78 @@
+import { GraphQLClientWrapper } from "./graphql-client";
+
+const mockRequest = jest.fn();
+const mockSetHeaders = jest.fn();
+
+jest.mock("graphql-request", () => ({
+  GraphQLClient: jest.fn().mockImplementation(() => ({
+    request: mockRequest,
+    setHeaders: mockSetHeaders,
+  })),
+}));
+
+describe("GraphQLClientWrapper", () => {
+  let clientWrapper: GraphQLClientWrapper;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    clientWrapper = new GraphQLClientWrapper("https://api.example.com/graphql");
+  });
+
+  it("should create GraphQLClient with endpoint and default headers", () => {
+    const { GraphQLClient } = require("graphql-request");
+    expect(GraphQLClient).toHaveBeenCalledWith(
+      "https://api.example.com/graphql",
+      { headers: {} }
+    );
+  });
+
+  it("should create GraphQLClient with custom headers", () => {
+    const headers = { Authorization: "Bearer token123" };
+    new GraphQLClientWrapper("https://api.example.com/graphql", headers);
+
+    const { GraphQLClient } = require("graphql-request");
+    expect(GraphQLClient).toHaveBeenCalledWith(
+      "https://api.example.com/graphql",
+      { headers }
+    );
+  });
+
+  it("should execute mutation successfully", async () => {
+    const mutation = "mutation { createUser(name: $name) { id } }";
+    const variables = { name: "John" };
+    const expectedResult = { createUser: { id: "123" } };
+
+    mockRequest.mockResolvedValue(expectedResult);
+
+    const result = await clientWrapper.executeMutation(mutation, variables);
+
+    expect(mockRequest).toHaveBeenCalledWith(mutation, variables);
+    expect(result).toEqual(expectedResult);
+  });
+
+  it("should handle GraphQL errors", async () => {
+    const mutation = "mutation { createUser(name: $name) { id } }";
+    const variables = { name: "John" };
+    const error = new Error("GraphQL error");
+
+    mockRequest.mockRejectedValue(error);
+
+    const consoleSpy = jest.spyOn(console, "error").mockImplementation();
+
+    await expect(
+      clientWrapper.executeMutation(mutation, variables)
+    ).rejects.toThrow("GraphQL error");
+
+    expect(consoleSpy).toHaveBeenCalledWith("GraphQL mutation failed:", error);
+
+    consoleSpy.mockRestore();
+  });
+
+  it("should set headers on the client", () => {
+    const newHeaders = { "X-API-Key": "api123" };
+
+    clientWrapper.setHeaders(newHeaders);
+
+    expect(mockSetHeaders).toHaveBeenCalledWith(newHeaders);
+  });
+});

package/src/graphql-client.ts

@@ -0,0 +1,25 @@
+import { GraphQLClient } from 'graphql-request';
+
+export class GraphQLClientWrapper {
+  private client: GraphQLClient;
+
+  constructor(endpoint: string, headers?: Record<string, string>) {
+    this.client = new GraphQLClient(endpoint, {
+      headers: headers || {}
+    });
+  }
+
+  async executeMutation(mutation: string, variables: Record<string, any>): Promise<any> {
+    try {
+      const result = await this.client.request(mutation, variables);
+      return result;
+    } catch (error) {
+      console.error('GraphQL mutation failed:', error);
+      throw error;
+    }
+  }
+
+  setHeaders(headers: Record<string, string>) {
+    this.client.setHeaders(headers);
+  }
+}

package/src/mapper.test.ts

@@ -0,0 +1,256 @@
+import fs from "fs";
+import path from "path";
+import { DataMapper } from "./mapper";
+import { GraphQLClientWrapper } from "./graphql-client";
+
+jest.mock("fs");
+jest.mock("./csv-reader");
+
+const mockFs = fs as jest.Mocked<typeof fs>;
+
+describe("DataMapper", () => {
+  let mockClient: jest.Mocked<GraphQLClientWrapper>;
+  let dataMapper: DataMapper;
+  const testBasePath = "/test/base/path";
+
+  beforeEach(() => {
+    mockClient = {
+      executeMutation: jest.fn(),
+      setHeaders: jest.fn(),
+    } as any;
+
+    dataMapper = new DataMapper(mockClient, testBasePath);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe("discoverMappings", () => {
+    it("should discover mapping files in alphabetical order", () => {
+      const mockFiles = ["users.json", "items.json", "orders.json"];
+      mockFs.readdirSync.mockReturnValue(mockFiles as any);
+
+      const consoleSpy = jest.spyOn(console, "log").mockImplementation();
+
+      const result = dataMapper.discoverMappings("configs/test");
+
+      expect(mockFs.readdirSync).toHaveBeenCalledWith(
+        path.resolve(testBasePath, "configs/test", "mappings")
+      );
+      expect(result).toEqual([
+        "configs/test/mappings/items.json",
+        "configs/test/mappings/orders.json",
+        "configs/test/mappings/users.json",
+      ]);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "Discovered 3 mapping files: items.json, orders.json, users.json"
+      );
+
+      consoleSpy.mockRestore();
+    });
+
+    it("should filter only JSON files", () => {
+      const mockFiles = ["users.json", "items.txt", "orders.json", "readme.md"];
+      mockFs.readdirSync.mockReturnValue(mockFiles as any);
+
+      const result = dataMapper.discoverMappings("configs/test");
+
+      expect(result).toEqual([
+        "configs/test/mappings/orders.json",
+        "configs/test/mappings/users.json",
+      ]);
+    });
+
+    it("should handle directory read errors", () => {
+      mockFs.readdirSync.mockImplementation(() => {
+        throw new Error("Directory not found");
+      });
+
+      const consoleSpy = jest.spyOn(console, "error").mockImplementation();
+
+      const result = dataMapper.discoverMappings("configs/nonexistent");
+
+      expect(result).toEqual([]);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Error reading mappings directory"),
+        expect.any(Error)
+      );
+
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe("processEntity", () => {
+    it("should process entity successfully", async () => {
+      const mockConfig = {
+        csvFile: "data/users.csv",
+        graphqlFile: "graphql/users.graphql",
+        mapping: {
+          name: "user_name",
+          email: "user_email",
+        },
+      };
+
+      const mockCsvData = [
+        { user_name: "John", user_email: "john@example.com" },
+        { user_name: "Jane", user_email: "jane@example.com" },
+      ];
+
+      const mockMutation =
+        "mutation CreateUser($name: String!, $email: String!) { createUser(input: { name: $name, email: $email }) { id } }";
+
+      mockFs.readFileSync
+        .mockReturnValueOnce(JSON.stringify(mockConfig))
+        .mockReturnValueOnce(mockMutation);
+
+      const { readCsvFile } = require("./csv-reader");
+      readCsvFile.mockResolvedValue(mockCsvData);
+
+      mockClient.executeMutation.mockResolvedValue({
+        createUser: { id: "123" },
+      });
+
+      const consoleSpy = jest.spyOn(console, "log").mockImplementation();
+
+      await dataMapper.processEntity("configs/test/mappings/users.json");
+
+      expect(mockFs.readFileSync).toHaveBeenCalledWith(
+        path.resolve(testBasePath, "configs/test/mappings/users.json"),
+        "utf8"
+      );
+      expect(readCsvFile).toHaveBeenCalledWith(
+        path.resolve(testBasePath, "configs/test", "data/users.csv")
+      );
+      expect(mockFs.readFileSync).toHaveBeenCalledWith(
+        path.resolve(testBasePath, "configs/test", "graphql/users.graphql"),
+        "utf8"
+      );
+
+      expect(mockClient.executeMutation).toHaveBeenCalledTimes(2);
+      expect(mockClient.executeMutation).toHaveBeenCalledWith(mockMutation, {
+        name: "John",
+        email: "john@example.com",
+      });
+      expect(mockClient.executeMutation).toHaveBeenCalledWith(mockMutation, {
+        name: "Jane",
+        email: "jane@example.com",
+      });
+
+      consoleSpy.mockRestore();
+    });
+
+    it("should handle GraphQL execution errors gracefully", async () => {
+      const mockConfig = {
+        csvFile: "data/users.csv",
+        graphqlFile: "graphql/users.graphql",
+        mapping: { name: "user_name" },
+      };
+
+      const mockCsvData = [{ user_name: "John" }];
+      const mockMutation =
+        "mutation CreateUser($name: String!) { createUser(input: { name: $name }) { id } }";
+
+      mockFs.readFileSync
+        .mockReturnValueOnce(JSON.stringify(mockConfig))
+        .mockReturnValueOnce(mockMutation);
+
+      const { readCsvFile } = require("./csv-reader");
+      readCsvFile.mockResolvedValue(mockCsvData);
+
+      mockClient.executeMutation.mockRejectedValue(new Error("GraphQL error"));
+
+      const consoleSpy = jest.spyOn(console, "error").mockImplementation();
+
+      await dataMapper.processEntity("configs/test/mappings/users.json");
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "✗ Failed to create entity for row:",
+        { user_name: "John" },
+        expect.any(Error)
+      );
+
+      consoleSpy.mockRestore();
+    });
+
+    it("should map CSV columns to GraphQL variables correctly", async () => {
+      const mockConfig = {
+        csvFile: "data/products.csv",
+        graphqlFile: "graphql/products.graphql",
+        mapping: {
+          name: "product_name",
+          price: "product_price",
+          sku: "product_sku",
+        },
+      };
+
+      const mockCsvData = [
+        {
+          product_name: "Widget",
+          product_price: "19.99",
+          product_sku: "W001",
+          extra_column: "ignored",
+        },
+      ];
+
+      const mockMutation =
+        "mutation CreateProduct($name: String!, $price: String!, $sku: String!) { createProduct(input: { name: $name, price: $price, sku: $sku }) { id } }";
+
+      mockFs.readFileSync
+        .mockReturnValueOnce(JSON.stringify(mockConfig))
+        .mockReturnValueOnce(mockMutation);
+
+      const { readCsvFile } = require("./csv-reader");
+      readCsvFile.mockResolvedValue(mockCsvData);
+
+      mockClient.executeMutation.mockResolvedValue({
+        createProduct: { id: "456" },
+      });
+
+      await dataMapper.processEntity("configs/test/mappings/products.json");
+
+      expect(mockClient.executeMutation).toHaveBeenCalledWith(mockMutation, {
+        name: "Widget",
+        price: "19.99",
+        sku: "W001",
+      });
+    });
+
+    it("should handle missing CSV columns gracefully", async () => {
+      const mockConfig = {
+        csvFile: "data/users.csv",
+        graphqlFile: "graphql/users.graphql",
+        mapping: {
+          name: "user_name",
+          email: "user_email",
+          phone: "user_phone",
+        },
+      };
+
+      const mockCsvData = [
+        { user_name: "John", user_email: "john@example.com" },
+      ];
+
+      const mockMutation =
+        "mutation CreateUser($name: String!, $email: String, $phone: String) { createUser(input: { name: $name, email: $email, phone: $phone }) { id } }";
+
+      mockFs.readFileSync
+        .mockReturnValueOnce(JSON.stringify(mockConfig))
+        .mockReturnValueOnce(mockMutation);
+
+      const { readCsvFile } = require("./csv-reader");
+      readCsvFile.mockResolvedValue(mockCsvData);
+
+      mockClient.executeMutation.mockResolvedValue({
+        createUser: { id: "789" },
+      });
+
+      await dataMapper.processEntity("configs/test/mappings/users.json");
+
+      expect(mockClient.executeMutation).toHaveBeenCalledWith(mockMutation, {
+        name: "John",
+        email: "john@example.com",
+      });
+    });
+  });
+});

package/src/mapper.ts

@@ -0,0 +1,80 @@
+import fs from 'fs';
+import path from 'path';
+import { readCsvFile, CsvRow } from './csv-reader';
+import { GraphQLClientWrapper } from './graphql-client';
+
+export interface MappingConfig {
+  csvFile: string;
+  graphqlFile: string;
+  mapping: Record<string, string>;
+}
+
+export class DataMapper {
+  private client: GraphQLClientWrapper;
+  private basePath: string;
+
+  constructor(client: GraphQLClientWrapper, basePath: string = process.cwd()) {
+    this.client = client;
+    this.basePath = basePath;
+  }
+
+  discoverMappings(configDir: string): string[] {
+    const mappingsPath = path.resolve(this.basePath, configDir, 'mappings');
+    
+    try {
+      const files = fs.readdirSync(mappingsPath);
+      const jsonFiles = files
+        .filter(file => file.endsWith('.json'))
+        .sort(); // Alphabetical order for consistent processing
+      
+      console.log(`Discovered ${jsonFiles.length} mapping files: ${jsonFiles.join(', ')}`);
+      return jsonFiles.map(file => path.join(configDir, 'mappings', file));
+    } catch (error) {
+      console.error(`Error reading mappings directory ${mappingsPath}:`, error);
+      return [];
+    }
+  }
+
+  async processEntity(configPath: string): Promise<void> {
+    console.log(`Processing entity: ${configPath}`);
+    
+    // Read mapping configuration
+    const configFullPath = path.resolve(this.basePath, configPath);
+    const config: MappingConfig = JSON.parse(fs.readFileSync(configFullPath, 'utf8'));
+    
+    // Extract config directory (parent of mappings directory)
+    const configDir = path.dirname(path.dirname(configFullPath));
+    
+    // Read CSV data (relative to config directory)
+    const csvPath = path.resolve(configDir, config.csvFile);
+    const csvData = await readCsvFile(csvPath);
+    
+    // Read GraphQL mutation (relative to config directory)
+    const graphqlPath = path.resolve(configDir, config.graphqlFile);
+    const mutation = fs.readFileSync(graphqlPath, 'utf8');
+    
+    // Process each row
+    for (const row of csvData) {
+      const variables = this.mapCsvRowToVariables(row, config.mapping);
+      
+      try {
+        const result = await this.client.executeMutation(mutation, variables);
+        console.log(`✓ Created entity with result:`, result);
+      } catch (error) {
+        console.error(`✗ Failed to create entity for row:`, row, error);
+      }
+    }
+  }
+
+  private mapCsvRowToVariables(row: CsvRow, mapping: Record<string, string>): Record<string, any> {
+    const variables: Record<string, any> = {};
+    
+    for (const [graphqlVar, csvColumn] of Object.entries(mapping)) {
+      if (row[csvColumn] !== undefined) {
+        variables[graphqlVar] = row[csvColumn];
+      }
+    }
+    
+    return variables;
+  }
+}