# schemas/options

## Purpose

Zod boundary schema for `BetterAuthSurrealAdapterOptions`. Drives the runtime
validation step inside `createBetterAuthSurrealAdapter` so callers cannot
construct an adapter against a malformed configuration. Failure raises
`BetterAuthSurrealError(INVALID_INPUT)` carrying the `ZodError` as `cause`,
which keeps the original field path + issue list available to error
reporters and OTel adapters.

## Features

- Structural validation of `client` (asserts `query`/`execute` methods).
- Optional-field gating for `modelToTable`, `idStrategy`, `linkFields`,
  `logger`.
- Embedded `LinkFieldMapSchema` reuse — invalid link-field shape surfaces
  inside the parent schema's `cause.issues`.
- Identifier-safe id-strategy union `"record-id" | "plain" | "ulid"`.

## Usage: Basic

```ts
import { BetterAuthSurrealAdapterOptionsSchema } from "@suaveplan/better-auth-surrealdb/schemas/options";

BetterAuthSurrealAdapterOptionsSchema.parse({
    client: surrealAdapterInstance,
});
```

## Usage: Advanced

```ts
import { BetterAuthSurrealAdapterOptionsSchema } from "@suaveplan/better-auth-surrealdb/schemas/options";

const result = BetterAuthSurrealAdapterOptionsSchema.safeParse({
    client: surrealAdapterInstance,
    idStrategy: "ulid",
    linkFields: { session: { userId: "user" } },
    modelToTable: (m) => `auth_${m}`,
});

if (!result.success) {
    console.error(result.error.issues);
} else {
    const opts = result.data; // typed
}
```

## API Reference

- `BetterAuthSurrealAdapterOptionsSchema: z.ZodObject` — boundary schema.
- `BetterAuthSurrealAdapterOptionsInput` — pre-parse type alias.

## Implementation Notes

`client` is validated via `z.custom` with a structural predicate (checks
`query` and `execute` are both functions) rather than `z.instanceof`,
because the spec accepts both `SurrealAdapter` instances and bespoke
`SurrealClientView` objects. The schema strips no keys (the parse pass is
permissive in case Better-Auth v1.x minor releases extend the contract);
the factory still narrows by destructuring only the fields it uses.

The validator deliberately returns the originally-supplied client
reference (Zod's `z.custom` preserves the input identity) rather than
reconstructing it — this preserves method identity and any private
state the supplied `SurrealAdapter` holds (connection pool, retry
counter, OTel context). Failing options surface a `ZodError` with the
full `issues` array, which the `createBetterAuthSurrealAdapter` factory
re-raises as `BetterAuthSurrealError(INVALID_INPUT)` with the `ZodError`
attached as `cause` so downstream log aggregators and OTel exporters get
the field-level diagnostics without rebuilding them from text.