deterministic-trilabel/README.md

🔗 Deterministic Trilabel Generate human-readable, deterministic URLs for multi-tenant applications. Instead of random strings or UUIDs, create memorable URLs like "happy-jump-cloud" that are: ✨ Deterministic - Same input always produces the same URL 🎯

# Deterministic Trilabel

A deterministic URL generation system that creates human-readable URLs using combinations of adjectives, verbs, and nouns. Perfect for generating consistent, memorable subdomains or URLs for your applications.

## Features

- Generates deterministic, human-readable URLs (e.g., "happy-jump-cloud")
- 140,608,000 possible unique combinations
- Support for exception keys (bypass URL generation for specific clients)
- Optional composite URL mode (client-route format)
- TypeScript support
- Zero dependencies
- Fully tested

## Installation

```bash
npm install deterministic-trilabel
# or
yarn add deterministic-trilabel
```

## Usage

### Basic Usage

```typescript
import { createLabels } from 'deterministic-trilabel';

// Create a URL generator with an exception key
const generateUrl = createLabels({
  exceptionKey: 'sportbuddy', // URLs for this client will bypass generation
});

// Generate URLs
generateUrl('client1', 'app'); // -> 'happy-jump-cloud'
generateUrl('client2', 'api'); // -> 'quick-run-river'
generateUrl('sportbuddy', 'app'); // -> 'app' (exception key bypass)
```

### Composite URL Mode

```typescript
// Create a generator that uses composite URLs (client-route format)
const generateCompositeUrl = createLabels({
  exceptionKey: 'sportbuddy',
  useCompositeUrls: true,
});

// Generate composite URLs
generateCompositeUrl('manchester-city', 'app'); // -> 'manchester-city-app'
generateCompositeUrl('liverpool', 'api'); // -> 'liverpool-api'
generateCompositeUrl('sportbuddy', 'app'); // -> 'app' (exception still works)
```

## API

### createLabels(options)

Creates a URL generator function with the specified options.

#### Options

- `exceptionKey` (string): Client name that should bypass URL generation
- `useCompositeUrls` (boolean, optional): When true, generates URLs in client-route format instead of word combinations. Defaults to false.

#### Returns

A function with the signature: `(clientName: string, routeName: string) => string`

### Validation Rules

Client names must:

- Be between 3 and 63 characters
- Contain only letters, numbers, and hyphens
- Not start or end with a hyphen
- Not contain consecutive hyphens

Route names must:

- Be between 2 and 16 characters
- Contain only letters, numbers, and hyphens

## Word Collections

The package includes:

- 520 adjectives (20 per letter A-Z)
- 520 verbs (20 per letter A-Z)
- 520 nouns (20 per letter A-Z)

Total possible combinations: 140,608,000

## Examples

```typescript
const generateUrl = createLabels({ exceptionKey: 'sportbuddy' });

// Regular clients get deterministic URLs
generateUrl('acme-corp', 'app'); // -> 'tiny-carry-teacher'
generateUrl('acme-corp', 'api'); // -> 'happy-jump-cloud'
generateUrl('acme-corp', 'web'); // -> 'quick-run-river'

// Exception key client gets route name as-is
generateUrl('sportbuddy', 'app'); // -> 'app'
generateUrl('sportbuddy', 'api'); // -> 'api'

// Composite mode
const compositeUrl = createLabels({
  exceptionKey: 'sportbuddy',
  useCompositeUrls: true,
});

compositeUrl('acme-corp', 'app'); // -> 'acme-corp-app'
compositeUrl('sportbuddy', 'app'); // -> 'app'
```

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.