first commit

docs/identity/auth/better-auth-surrealdb/src/schemas/options.md

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