Property Classifier

A TypeScript package that classifies property names and infers their JSON data types based on singular/plural form detection.

Features

• 🔍 Automatic Form Detection: Uses the pluralize library to accurately detect singular vs plural property names
• 🎯 Smart Type Inference: Applies pattern-matching rules to infer appropriate JSON data types
• 📋 Configurable Rules: Metadata-driven rules stored in JSON format
• ⚡ Fast & Efficient: No disk caching needed - the pluralize library is fast enough for real-time use
• 📊 Confidence Scoring: Returns confidence levels for each classification
• 🔧 TypeScript: Fully typed for better development experience

Installation

npm install

Quick Start

import { PropertyClassifier } from 'property-classifier';

const classifier = new PropertyClassifier();

// Classify a single property
const result = classifier.classify('users');
console.log(result);
// {
//   propertyName: 'users',
//   form: 'plural',
//   inferredType: 'array',
//   confidence: 'medium',
//   reasoning: 'Default: plural properties are arrays'
// }

// Classify multiple properties
const results = classifier.classifyBatch(['user', 'isActive', 'itemCount']);

How It Works

1. Form Detection (Singular vs Plural)

The classifier uses the pluralize npm package to determine if a property name is singular or plural:

• user → singular
• users → plural
• person → singular
• people → plural

2. Type Inference

Based on the form and pattern matching rules, the classifier infers the appropriate JSON data type:

Singular Properties

• isActive, hasPermission, canEdit → boolean
• itemCount, totalPrice, amount → number
• createdAt, updatedAt, timestamp → date
• name, email, title → string
• user, profile, data → object

Plural Properties

• users, items, products → array
• userIds, tags, categories → array

Special Cases

Some words have special handling defined in the rules:

• settings, metadata, config → object (even though plural-looking)
• news, series → array

API Reference

PropertyClassifier

Constructor

constructor(rulesPath?: string)

Creates a new classifier instance. Optionally provide a custom path to rules JSON file.

Methods

classify(propertyName: string): ClassificationResult

Classifies a single property name.

Returns:

{
  propertyName: string;
  form: 'singular' | 'plural';
  inferredType: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'date' | 'unknown';
  confidence: 'high' | 'medium' | 'low';
  reasoning?: string;
}

classifyBatch(propertyNames: string[]): ClassificationResult[]

Classifies multiple property names at once.

getRulesStats()

Returns statistics about the loaded rules:

{
  singularPatterns: number;
  pluralPatterns: number;
  specialCases: number;
}

Customizing Rules

Rules are stored in .metadata/parser/rules.json and consist of:

Structure

{
  "singularPatterns": [
    {
      "pattern": "^is[A-Z]",
      "inferredType": "boolean",
      "priority": 100,
      "description": "Properties starting with 'is' are typically boolean"
    }
  ],
  "pluralPatterns": [...],
  "specialCases": {
    "settings": "object",
    "metadata": "object"
  }
}

Pattern Priority

Higher priority patterns are checked first (0-100 scale):

• 100: High confidence patterns (boolean flags, timestamps)
• 90-95: Strong indicators (counts, IDs, money values)
• 80-85: Common patterns (names, text fields)
• 10: Default fallback patterns

Examples

Example 1: User Profile Schema

const classifier = new PropertyClassifier();

const properties = ['id', 'username', 'email', 'isVerified', 'followers', 'createdAt'];
const results = classifier.classifyBatch(properties);

// Generate schema
const schema = results.reduce((acc, result) => {
  acc[result.propertyName] = result.inferredType;
  return acc;
}, {});

console.log(schema);
// {
//   id: 'string',
//   username: 'string',
//   email: 'string',
//   isVerified: 'boolean',
//   followers: 'array',
//   createdAt: 'date'
// }

Example 2: E-commerce Product

const productProps = [
  'productId', 'name', 'description', 'price', 
  'inStock', 'tags', 'relatedProducts', 'reviewCount'
];

productProps.forEach(prop => {
  const result = classifier.classify(prop);
  console.log(`${prop}: ${result.inferredType} (${result.confidence})`);
});

// Output:
// productId: string (high)
// name: string (medium)
// description: string (medium)
// price: number (high)
// inStock: boolean (high)
// tags: array (medium)
// relatedProducts: array (medium)
// reviewCount: number (high)

Development

Build

npm run build

Run Examples

npm run dev

Use Cases

• API Schema Generation: Automatically infer JSON schema from property names
• Documentation: Generate type hints for API documentation
• Validation: Pre-validate expected data structures
• Code Generation: Generate TypeScript interfaces or database schemas
• Data Migration: Understand data structure from property names

License

MIT