# @sparring/tech-catalog

[![npm version](https://img.shields.io/npm/v/@sparring/tech-catalog.svg)](https://www.npmjs.com/package/@sparring/tech-catalog)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3%2B-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-16%2B-green.svg)](https://nodejs.org/)

A comprehensive catalog of 1094+ technologies, frameworks, libraries, and tech stacks with TypeScript support.

## Table of contents

- [Overview](#overview)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Use cases](#use-cases)
- [Examples](#examples)
- [Technical information](#technical-information)
- [Technology categories](#technology-categories)
- [Data structure](#data-structure)
- [TypeScript support](#typescript-support)
- [API reference](#api-reference)
  - [Core module](#core-module)
  - [Search module](#search-module)
  - [Filters module](#filters-module)
  - [Validators module](#validators-module)
- [Links](#links)
- [Contributing](#contributing)
- [License](#license)

## Overview

`@sparring/tech-catalog` is a curated, structured catalog of over 1094 modern technologies organized into 8 distinct categories. It provides a robust API for searching, filtering, and validating technology data with full TypeScript support.

### Key features

- **1094+ technologies**: Comprehensive catalog across 8 categories including languages, frameworks, libraries, databases, servers, tools, platforms, and complete tech stacks
- **Fuzzy search**: Advanced Levenshtein distance-based similarity matching for typo-tolerant searches
- **Zero dependencies**: No external runtime dependencies, keeping your bundle lean
- **Tree-shakeable**: Modular exports for optimal bundle size
- **Full TypeScript support**: Complete type definitions with type guards
- **Autocomplete ready**: Intelligent suggestion engine for building search interfaces
- **Validated**: Built-in validation utilities for data integrity
- **Stack analysis**: Detailed technology stacks with component relationships
- **Dual format**: Both CJS and ESM exports for maximum compatibility
- **Battle-tested**: 92 comprehensive tests ensuring reliability

## Installation

```bash
npm install @sparring/tech-catalog
```

```bash
yarn add @sparring/tech-catalog
```

```bash
pnpm add @sparring/tech-catalog
```

## Quick start

```typescript
import {
  getTechnologies,
  searchTech,
  autocomplete,
  getTechByName,
} from '@sparring/tech-catalog';

// Get all technologies
const technologies = getTechnologies();
console.log(`Total technologies: ${technologies.length}`);

// Find a specific technology
const react = getTechByName('React');
console.log(react); // { nombre: 'React', tipo: 'Framework' }

// Search with fuzzy matching (typo-tolerant)
const results = searchTech('recat'); // Typo intended
console.log(results[0].technology.nombre); // 'React'

// Autocomplete suggestions
const suggestions = autocomplete('java', 5);
// Returns: ['JavaScript', 'Java', 'JavaFX', ...]
```

## Use cases

This package is designed for various real-world scenarios:

### Build a technology search engine

Create a searchable database of technologies with typo-tolerant fuzzy search. Perfect for documentation sites, learning platforms, or tech directories.

```typescript
import { searchTech } from '@sparring/tech-catalog';

// Users can make typos and still find what they need
const results = searchTech('reactjs', { maxResults: 5 });
// Returns React and related technologies
```

### Implement smart autocomplete

Build intelligent autocomplete features for forms, search bars, or IDE plugins.

```typescript
import { autocomplete } from '@sparring/tech-catalog';

function handleInputChange(userInput: string) {
  const suggestions = autocomplete(userInput, 10);
  return suggestions.map((tech) => ({
    label: tech.nombre,
    category: tech.tipo,
  }));
}
```

### Validate tech stacks

Ensure technology combinations are valid and get detailed information about stack components.

```typescript
import { getStacks, getStacksByComponent } from '@sparring/tech-catalog';

// Find all stacks that use React
const reactStacks = getStacksByComponent('React');
// Returns: MERN, T3, Next.js stack, etc.
```

### Build recommendation systems

Analyze technology usage patterns and suggest related technologies or complete stacks.

```typescript
import { filterTechnologies, getStatistics } from '@sparring/tech-catalog';

const stats = getStatistics();
// Get insights: most popular categories, stack compositions, etc.

const frontendTech = filterTechnologies({
  types: ['Framework', 'Library'],
  nameContains: 'React',
});
```

### Technology analytics and reporting

Generate reports on technology landscapes, track trends, or build dashboards.

```typescript
import { getStatistics, getCategories } from '@sparring/tech-catalog';

const stats = getStatistics();
console.log(`Total technologies: ${stats.total}`);
console.log(`Categories: ${stats.byCategory}`);
```

## Examples

### Basic catalog access

```typescript
import { getTechnologies, getMetadata } from '@sparring/tech-catalog';

const metadata = getMetadata();
console.log(`${metadata.nombre} v${metadata.version}`);

const technologies = getTechnologies();
console.log(`Total: ${technologies.length} technologies`);
```

### Search with typo tolerance

```typescript
import { searchTech } from '@sparring/tech-catalog';

// User types 'recat' instead of 'react'
const results = searchTech('recat', { maxResults: 5 });

results.forEach((result) => {
  console.log(
    `${result.technology.nombre} (${(result.score * 100).toFixed(0)}% match)`
  );
});
```

### Autocomplete implementation

```typescript
import { autocomplete } from '@sparring/tech-catalog';

function handleInputChange(userInput: string) {
  const suggestions = autocomplete(userInput, 10);
  return suggestions.map((tech) => ({
    label: tech.nombre,
    category: tech.tipo,
  }));
}
```

### Filter frameworks by name

```typescript
import { filterTechnologies } from '@sparring/tech-catalog';

const reactFrameworks = filterTechnologies({
  types: ['Framework'],
  nameContains: 'React',
  excludeStacks: true,
});

reactFrameworks.forEach((tech) => {
  console.log(tech.nombre);
});
```

### Explore technology stacks

```typescript
import { getStacks } from '@sparring/tech-catalog';

const stacks = getStacks();

stacks.forEach((stack) => {
  console.log(`\n${stack.nombre}:`);
  stack.componentes.forEach((comp) => {
    console.log(`  - ${comp.nombre} (${comp.tipo})`);
  });
});
```

### Validate user input

```typescript
import {
  validateTechnology,
  sanitizeName,
} from '@sparring/tech-catalog/validators';

function addCustomTechnology(userInput: any) {
  // Sanitize name
  if (userInput.nombre) {
    userInput.nombre = sanitizeName(userInput.nombre);
  }

  // Validate
  const validation = validateTechnology(userInput);

  if (!validation.isValid) {
    throw new Error(`Invalid: ${validation.errors.join(', ')}`);
  }

  return userInput;
}
```

### Get statistics

```typescript
import { getStatistics } from '@sparring/tech-catalog';

const stats = getStatistics();

console.log(`Total technologies: ${stats.total}`);
console.log(`Stacks: ${stats.totalStacks}`);
console.log(`Simple technologies: ${stats.totalSimpleTechnologies}`);

console.log('\nBy category:');
Object.entries(stats.byCategory).forEach(([category, count]) => {
  console.log(`  ${category}: ${count}`);
});
```

## Technical information

### Requirements

- **Node.js**: 16.0.0 or higher
- **TypeScript**: 5.3 or higher (for TypeScript users)

### Package details

- **Zero runtime dependencies**: No external packages required at runtime
- **Bundle size**: Optimized with tree-shaking support for minimal footprint
- **Module formats**: Dual CJS and ESM exports for maximum compatibility
- **Type safety**: Full TypeScript support with strict mode enabled
- **Testing**: 92 comprehensive tests with 100% passing rate
- **Build tool**: Optimized with tsup for fast, efficient builds

### Compatibility

This package works in:
- Node.js environments (16+)
- Modern bundlers (webpack, Vite, Rollup, esbuild)
- TypeScript projects (5.3+)
- JavaScript projects (ES6+)

### Performance

- Fast searches with efficient fuzzy matching algorithms
- Optimized data structures for quick lookups
- Minimal memory footprint
- Tree-shakeable exports to include only what you use

## Technology categories

The catalog organizes technologies into 8 distinct categories:

1. **Language** (169 technologies) - Programming languages
   - JavaScript, TypeScript, Python, Rust, Go, Java, C++, etc.

2. **Framework** (315 technologies) - Web and application frameworks
   - React, Angular, Vue, Svelte, Next.js, Express, Django, etc.

3. **Library** (221 technologies) - Utility and helper libraries
   - Lodash, Axios, React Query, Zustand, RxJS, etc.

4. **Database** (96 technologies) - Database systems
   - PostgreSQL, MongoDB, Redis, MySQL, Supabase, Firebase, etc.

5. **Server** (49 technologies) - Server software
   - Nginx, Apache, Caddy, Tomcat, IIS, etc.

6. **Tool** (232 technologies) - Development tools
   - Webpack, Vite, ESLint, Prettier, Docker, Git, etc.

7. **Platform** (178 technologies) - Cloud platforms and services
   - AWS, Vercel, Netlify, Heroku, Cloudflare, Azure, etc.

8. **Stack** (51 technologies) - Complete technology stacks
   - MERN, MEAN, T3, LAMP, JAMStack, PERN, etc.

## Data structure

### Simple technology

```typescript
{
  nombre: 'React',
  tipo: 'Framework'
}
```

### Stack technology

```typescript
{
  nombre: 'MERN',
  tipo: 'Stack',
  componentes: [
    { nombre: 'MongoDB', tipo: 'Database' },
    { nombre: 'Express', tipo: 'Framework' },
    { nombre: 'React', tipo: 'Framework' },
    { nombre: 'Node.js', tipo: 'Platform' }
  ]
}
```

### Catalog metadata

```typescript
{
  nombre: 'SPARRING Technology Catalog',
  version: '3.0',
  total_tecnologias: 1094,
  categorias: {
    Language: 'Programming languages...',
    Framework: 'Web and application frameworks...',
    // ...
  }
}
```

## TypeScript support

Full TypeScript support with comprehensive type definitions:

```typescript
import type {
  Technology,
  SimpleTechnology,
  StackTechnology,
  TechnologyType,
  SearchOptions,
  SearchResult,
  FilterCriteria,
  ValidationResult,
} from '@sparring/tech-catalog';

// Type guard
import { isStackTechnology } from '@sparring/tech-catalog';

function processTechnology(tech: Technology) {
  if (isStackTechnology(tech)) {
    // Type is narrowed to StackTechnology
    console.log(tech.componentes);
  } else {
    // Type is SimpleTechnology
    console.log(tech.nombre);
  }
}
```

### Available types

- `Technology` - Union type of SimpleTechnology and StackTechnology
- `SimpleTechnology` - Non-stack technology
- `StackTechnology` - Stack with components
- `TechnologyType` - Category enum
- `StackComponent` - Component within a stack
- `Catalog` - Complete catalog structure
- `CatalogMetadata` - Metadata structure
- `SearchOptions` - Search configuration
- `SearchResult` - Search result with score
- `FilterCriteria` - Filter configuration
- `ValidationResult` - Validation response
- `CatalogStatistics` - Statistics structure

## API reference

### Core module

#### `getCatalog()`

Returns the complete catalog including metadata and technologies.

```typescript
import { getCatalog } from '@sparring/tech-catalog/core';

const catalog = getCatalog();
console.log(catalog._metadata.version);
console.log(catalog.tecnologias.length);
```

#### `getTechnologies()`

Returns an array of all technologies.

```typescript
import { getTechnologies } from '@sparring/tech-catalog/core';

const technologies = getTechnologies();
```

#### `getMetadata()`

Returns catalog metadata.

```typescript
import { getMetadata } from '@sparring/tech-catalog/core';

const metadata = getMetadata();
console.log(metadata.nombre); // 'CATÁLOGO SPARRING DE TECNOLOGÍAS'
console.log(metadata.version); // '3.0'
```

#### `getTechnologyCount()`

Returns the total number of technologies.

```typescript
import { getTechnologyCount } from '@sparring/tech-catalog/core';

const count = getTechnologyCount(); // 1094
```

#### `getTechsByType(type)`

Returns all technologies of a specific type.

```typescript
import { getTechsByType } from '@sparring/tech-catalog/core';

const frameworks = getTechsByType('Framework');
const languages = getTechsByType('Lenguaje');
```

#### `getTechsByTypes(types)`

Returns technologies matching any of the specified types.

```typescript
import { getTechsByTypes } from '@sparring/tech-catalog/core';

const techs = getTechsByTypes(['Framework', 'Librería']);
```

#### `getSimpleTechnologies()`

Returns all non-stack technologies.

```typescript
import { getSimpleTechnologies } from '@sparring/tech-catalog/core';

const simple = getSimpleTechnologies();
```

#### `getStacks()`

Returns all stack technologies with their components.

```typescript
import { getStacks } from '@sparring/tech-catalog/core';

const stacks = getStacks();
stacks.forEach((stack) => {
  console.log(stack.nombre);
  console.log(stack.componentes);
});
```

#### `getCategories()`

Returns all available technology categories.

```typescript
import { getCategories } from '@sparring/tech-catalog/core';

const categories = getCategories();
// ['LENGUAJE', 'FRAMEWORK', 'LIBRERÍA', ...]
```

#### `getTechByName(name)`

Finds a technology by exact name (case-insensitive).

```typescript
import { getTechByName } from '@sparring/tech-catalog/core';

const tech = getTechByName('JavaScript');
const alsoFound = getTechByName('javascript'); // Same result
```

#### `getTechByNameStrict(name)`

Finds a technology by exact name (case-sensitive).

```typescript
import { getTechByNameStrict } from '@sparring/tech-catalog/core';

const tech = getTechByNameStrict('JavaScript'); // Found
const notFound = getTechByNameStrict('javascript'); // undefined
```

#### `getTechsByPartialName(partialName, caseSensitive?)`

Finds all technologies whose names contain the search string.

```typescript
import { getTechsByPartialName } from '@sparring/tech-catalog/core';

const techs = getTechsByPartialName('Script');
// Returns: JavaScript, TypeScript, etc.
```

#### `techExists(name)`

Checks if a technology exists in the catalog.

```typescript
import { techExists } from '@sparring/tech-catalog/core';

if (techExists('React')) {
  console.log('React is in the catalog');
}
```

#### `getStatistics()`

Returns statistical information about the catalog.

```typescript
import { getStatistics } from '@sparring/tech-catalog/core';

const stats = getStatistics();
console.log(stats.total);
console.log(stats.byCategory);
console.log(stats.totalStacks);
```

#### `getCountByCategory(category)`

Returns the number of technologies in a specific category.

```typescript
import { getCountByCategory } from '@sparring/tech-catalog/core';

const frameworkCount = getCountByCategory('Framework');
```

#### `getMostPopularCategory()`

Returns the category with the most technologies.

```typescript
import { getMostPopularCategory } from '@sparring/tech-catalog/core';

const result = getMostPopularCategory();
console.log(result.category); // E.g., 'FRAMEWORK'
console.log(result.count); // E.g., 250
```

### Search module

#### `searchTech(query, options?)`

Searches for technologies with optional fuzzy matching.

```typescript
import { searchTech } from '@sparring/tech-catalog/search';

// Basic fuzzy search
const results = searchTech('recat');

// With options
const results = searchTech('react', {
  fuzzy: true,
  caseSensitive: false,
  maxResults: 10,
  categories: ['Framework', 'Librería'],
});

// Result structure
results.forEach((result) => {
  console.log(result.technology.nombre);
  console.log(result.score); // Similarity score (0-1)
  console.log(result.matches); // Matched fields
});
```

**Options:**

- `fuzzy` (boolean, default: true): Enable fuzzy matching
- `caseSensitive` (boolean, default: false): Case-sensitive search
- `maxResults` (number, default: 20): Maximum number of results
- `categories` (array, optional): Filter by technology types

#### `searchByName(name, maxResults?)`

Simple name-based search with scoring.

```typescript
import { searchByName } from '@sparring/tech-catalog/search';

const results = searchByName('JavaScript', 5);
```

#### `autocomplete(input, maxSuggestions?, filterByType?)`

Returns autocomplete suggestions.

```typescript
import { autocomplete } from '@sparring/tech-catalog/search';

// Basic autocomplete
const suggestions = autocomplete('reac', 5);

// With type filter
const frameworks = autocomplete('reac', 5, ['Framework']);
```

### Filters module

#### `filterTechnologies(criteria)`

Filters technologies based on multiple criteria.

```typescript
import { filterTechnologies } from '@sparring/tech-catalog/filters';

const results = filterTechnologies({
  types: ['Framework', 'Librería'],
  nameContains: 'React',
  caseSensitive: false,
  excludeStacks: true,
  onlyStacks: false,
});
```

**Criteria:**

- `types` (array): Filter by technology types
- `nameContains` (string): Name must contain this string
- `caseSensitive` (boolean): Case-sensitive name matching
- `excludeStacks` (boolean): Exclude stack technologies
- `onlyStacks` (boolean): Only stack technologies

#### `getStacksByComponent(componentName)`

Finds stacks containing a specific component.

```typescript
import { getStacksByComponent } from '@sparring/tech-catalog/filters';

const stacks = getStacksByComponent('React');
// Returns stacks like MERN, T3, etc.
```

#### `getStacksByComponentType(componentType)`

Finds stacks with components of a specific type.

```typescript
import { getStacksByComponentType } from '@sparring/tech-catalog/filters';

const stacks = getStacksByComponentType('Framework');
```

#### `getTechnologiesUsedInStacks()`

Returns all technologies that appear in stacks.

```typescript
import { getTechnologiesUsedInStacks } from '@sparring/tech-catalog/filters';

const usedInStacks = getTechnologiesUsedInStacks();
```

#### `getStandaloneTechnologies()`

Returns technologies not used in any stack.

```typescript
import { getStandaloneTechnologies } from '@sparring/tech-catalog/filters';

const standalone = getStandaloneTechnologies();
```

#### `sortByName(technologies, ascending?)`

Sorts technologies alphabetically.

```typescript
import { sortByName } from '@sparring/tech-catalog/filters';

const sorted = sortByName(technologies, true); // A-Z
const reversed = sortByName(technologies, false); // Z-A
```

#### `sortByType(technologies, typeOrder?)`

Sorts technologies by type, then by name.

```typescript
import { sortByType } from '@sparring/tech-catalog/filters';

const sorted = sortByType(technologies);

// Custom order
const customSorted = sortByType(technologies, [
  'Stack',
  'Framework',
  'Lenguaje',
]);
```

### Validators module

#### `validateTechnology(tech)`

Validates a technology object.

```typescript
import { validateTechnology } from '@sparring/tech-catalog/validators';

const result = validateTechnology({
  nombre: 'React',
  tipo: 'Framework',
});

if (!result.isValid) {
  console.error(result.errors);
}
```

#### `isValidTechnologyType(type)`

Checks if a string is a valid technology type.

```typescript
import { isValidTechnologyType } from '@sparring/tech-catalog/validators';

if (isValidTechnologyType('Framework')) {
  // Valid type
}
```

#### `validateStack(tech)`

Validates a stack technology structure.

```typescript
import { validateStack } from '@sparring/tech-catalog/validators';

const result = validateStack(stackTech);
```

#### `validateCatalog(technologies)`

Checks catalog consistency and integrity.

```typescript
import { validateCatalog } from '@sparring/tech-catalog/validators';
import { getTechnologies } from '@sparring/tech-catalog/core';

const result = validateCatalog(getTechnologies());
console.log(result.errors);
console.log(result.warnings);
```

#### `sanitizeName(name)`

Cleans and normalizes a technology name.

```typescript
import { sanitizeName } from '@sparring/tech-catalog/validators';

const clean = sanitizeName('  React   Native  ');
// 'React Native'
```

#### `validateSearchOptions(options)`

Validates search options object.

```typescript
import { validateSearchOptions } from '@sparring/tech-catalog/validators';

const result = validateSearchOptions({
  fuzzy: true,
  maxResults: 10,
  categories: ['Framework'],
});
```

## Links

- **Homepage**: https://www.686f6c61.dev
- **Repository**: https://github.com/686f6c61/npm-tech-catalog
- **Issues**: https://github.com/686f6c61/npm-tech-catalog/issues
- **npm package**: https://www.npmjs.com/package/@sparring/tech-catalog

## Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository at https://github.com/686f6c61/npm-tech-catalog
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## License

MIT License - see LICENSE file for details.

---

Made with precision by SPARRING | https://www.686f6c61.dev