first commit

docs/foundation/data/validation/src/schemas/object/object.md

@@ -0,0 +1,77 @@
+# 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.