tr-identity

Features

• ✅ TCKN ve Vergi No doğrulama (checksum dahil)
• 🔮 Otomatik tamamlama — 9 haneli TCKN'yi 11 haneye tamamlar
• 🔍 Akıllı tip algılama — TCKN mi VERGI_NO mu olduğunu çıkarır
• ⚛️ useIdentity hook — debounce, status yönetimi, suggestion
• 🪶 ~5KB minified + gzip, sıfır bağımlılık (React peer dep)
• 🔷 Tam TypeScript desteği — .d.ts dahil

Installation

npm install tr-identity
# or
pnpm add tr-identity
# or
yarn add tr-identity

React 17+ gereklidir (hook kullanımı için).
Sadece processTRId kullanacaksanız React bağımlılığı gerekmez.

Quick Start

Core — processTRId

import { processTRId } from 'tr-identity'

const result = processTRId('12345678902')

console.log(result)
// {
//   type: 'TCKN',
//   valid: true,
//   completed: '12345678902',
//   suggestion: null,
//   original: '12345678902'
// }

React Hook — useIdentity

import { useIdentity } from 'tr-identity'

function IdentityInput() {
  const { raw, state, detectedLabel, errorMessage, handleChange, applySuggestion } = useIdentity({
    debounceMs: 500,
    onCommit: (value) => console.log('Committed:', value),
  })

  return (
    <div>
      <input
        value={raw}
        onChange={(e) => handleChange(e.target.value)}
        placeholder="TC Kimlik veya Vergi No"
      />

      {detectedLabel && <span>{detectedLabel}</span>}
      {errorMessage && <span style={{ color: 'red' }}>{errorMessage}</span>}

      {state.status === 'invalid' && state.suggestion && (
        <button onClick={applySuggestion}>
          Öneriyi uygula: {state.suggestion}
        </button>
      )}
    </div>
  )
}

API Reference

processTRId(input, hint?)

Girilen kimlik numarasını doğrular ve analiz eder.

function processTRId(
  input: string | number | null | undefined,
  hint?: TRIdType
): TRIdResult

| Parametre | Tip | Açıklama | |-----------|-----|----------| | input | string \| number \| null \| undefined | Ham kimlik numarası | | hint | 'TCKN' \| 'VERGI_NO' | (Opsiyonel) Tip zorlaması |

TRIdResult

interface TRIdResult {
  type: 'TCKN' | 'VERGI_NO' | null  // Algılanan tip
  valid: boolean                      // Checksum geçerli mi?
  completed: string | null            // Geçerliyse tam numara
  suggestion: string | null           // Hatalıysa önerilen düzeltme
  original: string                    // Orijinal girdi
  error?: TRIdError                   // Hata kodu (varsa)
}

TRIdError kodları

| Kod | Açıklama | |-----|----------| | INVALID_FORMAT | Rakam dışı karakter veya boş | | INVALID_CHECKSUM | Checksum geçersiz | | TOO_SHORT | Minimum uzunluktan kısa | | TOO_LONG | Maksimum uzunluktan uzun | | INCOMPLETE | Tamamlanabilir ama eksik (ör. 9 haneli TCKN) |

useIdentity(options?)

Debounce'lu, durum yönetimli React hook.

function useIdentity(options?: UseIdentityOptions): UseIdentityReturn

UseIdentityOptions

| Seçenek | Tip | Varsayılan | Açıklama | |---------|-----|-----------|----------| | debounceMs | number | 600 | Doğrulama gecikmesi (ms) | | onCommit | (value: string) => void | — | Değer kesinleştiğinde çağrılır |

UseIdentityReturn

| Alan | Tip | Açıklama | |------|-----|----------| | raw | string | Kullanıcının girdiği ham değer | | state | IdentityState | Detaylı durum nesnesi | | detectedLabel | string \| null | "T.C. Kimlik No" veya "Vergi No" | | errorMessage | string \| null | Türkçe hata mesajı | | handleChange | (value: string) => void | Input onChange handler | | applySuggestion | () => void | Önerilen değeri uygular | | reset | () => void | State'i sıfırlar |

IdentityState

interface IdentityState {
  status: 'idle' | 'typing' | 'valid' | 'autocompleted' | 'invalid'
  type: 'TCKN' | 'VERGI_NO' | null
  completed: string | null
  suggestion: string | null
  error: TRIdError | null
}

Status Flow

idle → typing → valid
    ↘ autocompleted   (9 haneli TCKN otomatik tamamlandı)
    ↘ invalid         (checksum hatalı veya format yanlış)

Examples

Sadece Vergi No doğrula

import { processTRId } from 'tr-identity'

const result = processTRId('1234567890', 'VERGI_NO')

if (result.valid) {
  console.log('Geçerli Vergi No:', result.completed)
} else {
  console.log('Hata:', result.error)
}

9 haneli TCKN'yi tamamla

const result = processTRId('123456789')
// result.error === 'INCOMPLETE'
// result.suggestion === '12345678902'  ← otomatik tamamlanmış

React Hook Form ile

import { useEffect } from 'react'
import { useForm } from 'react-hook-form'
import { useIdentity } from 'tr-identity'

function Form() {
  const { setValue, register } = useForm()
  const { raw, state, detectedLabel, errorMessage, handleChange } = useIdentity({
    onCommit: (value) => setValue('identity', value),
  })

  return (
    <div>
      <input
        {...register('identity')}
        value={raw}
        onChange={(e) => handleChange(e.target.value)}
        placeholder={detectedLabel ?? 'TC Kimlik veya Vergi No'}
      />
      {errorMessage && <p>{errorMessage}</p>}
    </div>
  )
}

Tip algılama

import { processTRId } from 'tr-identity'

// 10 haneli → Vergi No checksum geçerliyse VERGI_NO, değilse TCKN olarak işlenir
const r1 = processTRId('1234567890')  // type: 'VERGI_NO' veya 'TCKN'
const r2 = processTRId('12345678902') // type: 'TCKN' (11 hane → her zaman TCKN)

Validation Rules

TCKN (T.C. Kimlik No)

• 11 hane, ilk hane 0 olamaz
• Checksum: İlk 9 hanenin tek/çift toplamlarından 10. ve 11. haneler türetilir
• 9 hane verilirse → otomatik tamamlanır (INCOMPLETE + suggestion)

Vergi Kimlik No

• Tam olarak 10 hane
• Checksum: Her hanenin ağırlıklı toplamından son hane türetilir

TypeScript

Tüm tipler dist/index.d.ts içinde ship edilir, ayrıca kurulum gerekmez.

import type {
  TRIdType,
  TRIdResult,
  TRIdError,
  IdentityState,
  UseIdentityOptions,
  UseIdentityReturn,
} from 'tr-identity'

Changelog

0.1.0

• İlk yayın
• processTRId core utility
• useIdentity React hook
• TCKN & Vergi No checksum doğrulama
• Otomatik tamamlama desteği

License

MIT © Hamza Kaya