# person

Build and validate person information

Canonical URL: https://docs.paradoc.dev/sdk/primitives/person/

Build and validate person information. The Person primitive captures individual name components and personal details.

## Examples

### Creating persons

```ts
// Object pattern
const person = p.person({
  name: 'John Michael Smith'
})

// Builder pattern
const person = p.person()
  .name('John Michael Smith')
  .title('Dr.')
  .firstName('John')
  .middleName('Michael')
  .lastName('Smith')
  .suffix('Jr.')
  .build()

// Copy and modify
const updated = p.person()
  .from(person)
  .title('Prof.')
  .build()
```

### Parsing external data

```ts
// Parse unknown input (throws on error)
const person = p.person.parse(jsonData)

// Safe parsing (returns result object)
const result = p.person.safeParse(jsonData)
if (result.success) {
  console.log(`Name: ${result.data.name}`)
} else {
  console.error(result.error.message)
}
```

### Using with forms

```ts
const form = p.form({
  name: 'registration',
  fields: {
    applicant: { type: 'person', label: 'Applicant Information' }
  }
})

const filled = form.fill({
  fields: {
    applicant: p.person()
      .name('Jane Doe')
      .firstName('Jane')
      .lastName('Doe')
      .build()
  }
})
```

## API

### Object Pattern

```ts
p.person(input: Person): Person
```

Pass a Person object for validation. Returns the validated Person or throws on error.

```ts
const person = p.person({ name: 'Jane Doe' })
```

### Builder Pattern

Chain methods to build a Person value incrementally:

Start with `p.person()`. Each method returns `PersonBuilder` and can be chained.

| Method | Description |
| --- | --- |
| `name(value: string)` | Set full display name |
| `title(value: string \| undefined)` | Set honorific (Mr., Dr., etc.) |
| `firstName(value: string \| undefined)` | Set given/first name |
| `middleName(value: string \| undefined)` | Set middle name(s) |
| `lastName(value: string \| undefined)` | Set family/last name |
| `suffix(value: string \| undefined)` | Set suffix (Jr., III, etc.) |
| `from(value: Person)` | Initialize from existing Person |

Terminal methods return `Person`.

| Method | Description |
| --- | --- |
| `build()` | Build and validate |

### Static Methods

| Method | Returns | Description |
| --- | --- | --- |
| `parse(input: unknown)` | `Person` | Parse unknown input (throws on error) |
| `safeParse(input: unknown)` | `Result<Person>` | Parse unknown input (returns result object) |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | Complete display name. |
| `title` | `string?` | Honorific or title (Mr., Mrs., Dr., Prof.). |
| `firstName` | `string?` | Given name or first name. |
| `middleName` | `string?` | Middle name(s). |
| `lastName` | `string?` | Family name or surname. |
| `suffix` | `string?` | Name suffix (Jr., Sr., III, PhD, Esq.). |

## Common Titles

| Title   | Usage                           |
| ------- | ------------------------------- |
| `Mr.`   | Adult male                      |
| `Mrs.`  | Married female                  |
| `Ms.`   | Female (marital status neutral) |
| `Miss`  | Unmarried female                |
| `Dr.`   | Doctor (medical or academic)    |
| `Prof.` | Professor                       |
| `Rev.`  | Religious leader                |
| `Hon.`  | Judge or official               |

## Common Suffixes

| Suffix            | Meaning                      |
| ----------------- | ---------------------------- |
| `Jr.`             | Junior (same name as father) |
| `Sr.`             | Senior                       |
| `II`, `III`, `IV` | Generational                 |
| `PhD`             | Doctor of Philosophy         |
| `MD`              | Medical Doctor               |
| `Esq.`            | Esquire (attorney)           |
| `CPA`             | Certified Public Accountant  |

## Validation

The Person primitive validates:

* `name` must be a non-empty string
* All other fields are optional

```ts
// Valid
p.person({ name: 'John Doe' })
p.person({
  name: 'Dr. John Michael Smith Jr.',
  title: 'Dr.',
  firstName: 'John',
  middleName: 'Michael',
  lastName: 'Smith',
  suffix: 'Jr.'
})

// Invalid - throws Error
p.person({})

p.person({ name: '' })
```

## Related

* [Primitives Overview](/sdk/primitives) - All available primitives
* [Organization](/sdk/primitives/organization) - Organization information
* [Person Field](/sdk/artifacts/form/field#entity) - Person field type