# ObjectSchema

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

`ObjectSchema<S>` validates plain JavaScript objects against a named-key shape. Each key in the shape is validated against its corresponding schema, and errors carry full dot-path information. Three modes control unknown key handling: `strip` (default, silently removes extras), `strict` (rejects extras), and `passthrough` (copies extras to output). Rich shape-manipulation builders — `pick`, `omit`, `partial`, `extend`, `merge` — make it easy to derive new schemas from existing ones without duplication.

All builder methods return new `ObjectSchema` instances; the original is never modified.

## Features

- Type check: rejects non-objects, null, and arrays with `VALIDATION.INVALID_TYPE`
- Field validation with per-field error paths
- Three unknown-key modes: `strip`, `strict`, `passthrough`
- `pick(keys)` — project to a subset of keys
- `omit(keys)` — exclude keys
- `partial()` — make all fields optional
- `required()` — return schema as-is (identity, for symmetry)
- `extend(shape)` — add/override fields
- `merge(other)` — combine with another `ObjectSchema`

## Usage: Basic Example

```typescript
import { object, string, number } from "@suaveplan/validation";

const User = object({ name: string(), age: number() });
const user = User.parse({ name: "Alice", age: 30 });
// { name: "Alice", age: 30 }
```

## Usage: Advanced Example

```typescript
import { object, string, number } from "@suaveplan/validation";

const BaseUser = object({ id: string().uuid(), name: string() });
const AdminUser = BaseUser.extend({ role: string(), level: number().int() });
const PartialUpdate = AdminUser.partial().omit(["id"]);

const update = PartialUpdate.parse({ name: "Bob" });
// { name: "Bob" } — all fields optional, id omitted

const strict = AdminUser.strict();
strict.parse({ id: "...", name: "Alice", role: "admin", level: 1, extra: true });
// throws: Unrecognized key(s): extra
```

## API Reference

### `object<S extends ObjectShape>(shape: S): ObjectSchema<S>`

Factory with default `strip` mode.

### Mode methods (return new `ObjectSchema<S>`)

- `strict()` — reject unknown keys with `VALIDATION.OBJECT.UNRECOGNIZED_KEYS`
- `passthrough()` — copy unknown keys to output
- `strip()` — silently drop unknown keys (default)

### Shape manipulation methods

- `pick<K>(keys: K[]): ObjectSchema<Pick<S, K>>` — subset of keys
- `omit<K>(keys: K[]): ObjectSchema<Omit<S, K>>` — exclude keys
- `partial(): ObjectSchema<...>` — wrap all values in `OptionalSchema`
- `required(): ObjectSchema<S>` — identity (for symmetry with `partial`)
- `extend<E>(shape: E): ObjectSchema<S & E>` — add/override fields
- `merge<E>(other: ObjectSchema<E>): ObjectSchema<S & E>` — merge shapes

## Implementation Notes

- Field errors are reported under the field's key path. Nested object errors propagate the full path chain.
- `partial()` wraps each field schema with `.optional()`, so the output type has all values as `T | undefined`.
- `passthrough` copies unknown keys before iterating known ones, then known-key parsing runs normally on top.
- `strict` checks for unknown keys using a `Set` of shape keys — O(n) where n = number of input keys.