numsy

๐Ÿ“ฑ Numsy - A light-weight ๐Ÿ”ข Numsy

npm version License: MIT pnpm

A TypeScript-based phone ๐Ÿ”ข Numsy with CSV/Excel parsing capabilities built with NestJS. This application validates and sanitizes Indian phone numbers, providing a clean way to process bulk contact data.

๐Ÿš€ Features

๐Ÿ“‹ Supported Fields

Required Field: Phone Numbers

The application focuses on extracting phone numbers and recognizes 120+ field name variations, including:

Common Names:

Carrier/Type Specific:

Context Specific:

Abbreviated:

And many more variations with different separators (spaces, underscores, dots, etc.)

The system uses regex-based pattern matching to intelligently detect phone columns regardless of naming convention.

Optional Fields (Preserved if Present)

All other fields in your CSV/Excel file are optional and will be preserved in the output:

๐Ÿ› ๏ธ Tech Stack

๐Ÿ“ฆ Installation

Prerequisites

Install pnpm (if not already installed):

npm install -g pnpm
# or use Node.js Corepack
corepack enable

Setup

  1. Clone the repository:
cd number-processor
  1. Install dependencies:
pnpm install
  1. Build the project:
pnpm run build

๐ŸŽฏ Usage

Development Mode

Start the development server with hot-reload:

pnpm run start:dev

The application will be available at http://localhost:3000

Production Mode

Build and run in production:

pnpm run build
pnpm run start:prod

๐Ÿ“ API Endpoints

Health Check

GET /api/health

Returns server health status.

Upload File

POST /api/upload

Request:

Response:

{
  "success": true,
  "message": "File processed successfully",
  "downloadId": "processed_1234567890",
  "summary": {
    "totalRecords": 100,
    "validRecords": 85,
    "invalidRecords": 15,
    "phoneColumnDetected": "phone",
    "analytics": {
      "totalNumbersExtracted": 120,
      "totalValidNumbers": 85,
      "totalInvalidNumbers": 35,
      "recordsWithMultipleNumbers": 18,
      "averageNumbersPerRecord": 1.2,
      "duplicateNumbers": 5,
      "uniqueValidNumbers": 80
    }
  }
}

Download Processed Files

GET /api/download/:id

Downloads a ZIP file containing:

  1. validnumbers*.csv - All valid phone numbers with associated data
  2. invalidnumbers*.csv - All invalid phone numbers with validation reasons
  3. analytics_*.txt - Comprehensive analytics report

Analytics Report Contents

The analytics text file includes:

Summary Statistics:

Carrier Series Distribution:

Top Number Prefixes:

Duplicate Detection:

Field Distribution:

Validation Details:

๐Ÿ”ง Phone Number Extraction & Validation

Multiple Numbers Per Row

The application can now extract and process multiple phone numbers from a single cell:

Supported Separators:

Example Input:

Customer Name,Mobile Number,City
John Doe,9876543210 / 8765432109,Mumbai
Jane Smith,7654321098-9876543211,Delhi
Bob Wilson,8765432109  9876543212,Bangalore

Output Behavior:

Analytics Provided:

Validation Rules

Valid Numbers:

Automatic Sanitization:

Examples of Valid Inputs

Single Numbers:

Multiple Numbers (Separated):

Examples of Valid Inputs

Invalid Numbers

๐Ÿ“ Project Structure

number-processor/
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ controllers/
โ”‚   โ”‚   โ””โ”€โ”€ app.controller.ts          # Main API controller
โ”‚   โ”œโ”€โ”€ services/
โ”‚   โ”‚   โ”œโ”€โ”€ phone-validator.service.ts # Phone validation logic
โ”‚   โ”‚   โ”œโ”€โ”€ file-parser.service.ts     # CSV/Excel parsing
โ”‚   โ”‚   โ””โ”€โ”€ file-processor.service.ts  # File processing orchestration
โ”‚   โ”œโ”€โ”€ app.module.ts                  # Root module
โ”‚   โ””โ”€โ”€ main.ts                        # Application entry point
โ”œโ”€โ”€ public/
โ”‚   โ””โ”€โ”€ index.html                     # Web UI
โ”œโ”€โ”€ uploads/                           # Temporary upload directory
โ”œโ”€โ”€ temp/                              # Temporary processing directory
โ”œโ”€โ”€ package.json
โ”œโ”€โ”€ tsconfig.json
โ”œโ”€โ”€ nest-cli.json
โ””โ”€โ”€ README.md

๐ŸŽจ Code Standards

Naming Conventions

Comments

Example

/**
 * Validates and sanitizes a phone number
 * @param phoneNumber - The phone number to validate
 * @returns PhoneValidationResult object with validation details
 */
validateAndSanitize(phoneNumber: string): PhoneValidationResult {
  // Implementation
}

๐Ÿงช Testing

Run tests:

pnpm test

Run tests with coverage:

pnpm run test:cov

๏ฟฝ Publishing to NPM

This package is ready to be published to NPM. See the publishing guides:

Quick Publish

pnpm login
pnpm publish --access public

Users can then install it:

pnpm add @numsy

๏ฟฝ๐Ÿ”’ Security Features

๐Ÿ“Š Sample Data Format

Input CSV/Excel Format

name,phone,address
John Doe,9876543210,Mumbai
Jane Smith,98765-43210,Delhi
Bob Wilson,+91 9876543210,Bangalore

Output Format

valid_numbers.csv:

name,phone,address,originalPhone,sanitizedPhone,validationStatus
John Doe,9876543210,Mumbai,9876543210,9876543210,Valid

invalid_numbers.csv:

name,phone,address,originalPhone,sanitizedPhone,validationStatus,validationReason
Invalid User,12345,Chennai,12345,12345,Invalid,Invalid format - must be 10 digits

๐Ÿค Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

๐Ÿ“„ License

This project is licensed under the MIT License.

๐Ÿ‘ฅ Author

Your Name

๐Ÿ› Known Issues

๐Ÿš€ Future Enhancements

๐Ÿ“ž Support

For issues, questions, or contributions, please open an issue on GitHub.

Made with โค๏ธ using NestJS and TypeScript

This site is open source. Improve this page.